gtpc2m9q | C/C++ Language Support User's Guide |
This function sends a message to the system operator or any other CRAS
terminal. Chaining of messages and an optional header are additional
features offered by this function.
Format
#include <tpfapi.h>
int wtopc(const char * text_ptr, long int rout,
enum t_wtopc_chain chain, const void *header_ptr);
- text_ptr
- Pointer to the message to be sent.
- rout
- Integer containing the addition of routing destinations as defined in
tpfapi.h. Valid routing destinations are
WTOPC_EBROUT, WTOPC_RO, WTOPC_PRC, WTOPC_TAPE, WTOPC_DASD, WTOPC_COMM,
WTOPC_AUDT.
WTOPC_UNSOL can be coded to send unsolicited messages to remote terminals
specified in EBROUT. (Both WTOPC_EBROUT and WTOPC_UNSOL have to be
coded.) An additional routing destination receives the message as a
solicited message.
0 can be entered to indicate that the WTOPC_EBROUT value is to be
used.
- chain
- This argument must belong to the enumeration type t_wtopc_chain, defined
in tpfapi.h, specifying ONLY 1 of the following
values:
- WTOPC_NO_CHAIN
- Specifies that the current WTOPC message should not be chained
to a previous WTOPC message.
- WTOPC_CHAIN
- Specifies that current WTOPC message should be chained to a previous WTOPC
message.
- WTOPC_CHAIN_END
- Specifies that current WTOPC message is the end of a chain of
messages.
- WTOPC_NO_PAGE
- Similar to WTOPC_NO_CHAIN in that no chaining or paging will be
used.
- WTOPC_PAGE
- Specifies that the current WTOPC message will be chained and will use the
page support for large messages. Existing paged messages that are being
controlled by this ECB are terminated.
- WTOPC_PAGE_END
- Similar to WTOPC_CHAIN_END in that it signals the service routine to end
the current message chain.
- header_ptr
- If a header is desired, this argument points to a header structure as
defined in tpfapi.h. If a header is not desired,
WTOPC_NO_HEADER, defined in tpfapi.h, can be supplied as the
argument. The fields in the header structure are defined as
follows:
- wtopc_prefix_pointer
- char pointer to a 4-character prefix in the header. This field has
a default (NULL entered) of the name of the program which called the wtopc
function.
- wtopc_number
- short int number field in the header from 0-9999. This field
has no default value except when the whole header is defaulted, as explained
below.
- wtopc_letter
- char letter field in the header. This field has a default (\0
entered) of the letter I.
- wtopc_time
- This field must belong to the enumeration type t_wtopc_time, defined in
tpfapi.h, specifying one of the following times:
- WTOPC_SYS_TIME
- Specifies system time should be included in the header.
- WTOPC_SUBSYS_TIME
- Specifies subsystem time should be included in the header.
- WTOPC_NO_TIME
- Specifies that no time should be included in the header.
This field has a default (0 entered) of WTOPC_SUBSYS_TIME.
This parameter has a default (NULL entered) of all the individual default
fields, as defined previously, with the number 1 used as the default for the
number field.
Normal Return
Return Codes:
- 0
- WTOPC_SUCCESS - Normal return code. No special action should be
taken.
- 1
- WTOPC_PAGE_STOP - The caller should send no more lines or pages.
Either the timeout value for ZPAGE was reached or another long message was
sent.
- 2
- WTOPC_NEXT_PAGE - The caller is authorized to send more output that will
follow the previous page.
Error Return
Not applicable.
Programming Considerations
- text_ptr must point to a message that is NULL terminated whose length is
no greater than 255 bytes.
- There are defaults for all the different parts of the header, as defined
above, except for the number field when the whole header is NOT
defaulted. In this case the number field MUST be supplied.
- wtopc_insert_header and wtopc_routing_list are functions available,
defined in tpfapi.h, that simplify the coding of the
parameter list for the wtopc function.
- WTOPC_TEXT, defined in tpfapi.h, is an alternate way to
call this function when the parameter list consists of an address of the text
and the rest NULLs for the defaults.
- If WTOPC_PAGE is specified, then the ROUT parameter must contain at least
EBROUT.
- WTOPC_ UNSOL and WTOPC_CHAIN are mutually exclusive. If either
WTOPC_CHAIN or WTOPC_CHAIN_END is specified, WTOPC_UNSOL cannot be
specified.
- The message text can contain the following number of characters:
- When UNSOL=NO
- If a message header is specified, a maximum of 235 characters.
- If no message header is specified, a maximum of 255 characters.
- When UNSOL=YES
- If a message header is specified, a maximum of 161 characters.
- If no message header is specified, a maximum of 180 characters.
- WTOPC_PAGE and WTOPC_UNSOL are mutually exclusive.
TARGET(TPF) to ISO-C migration consideration |
---|
The wtopc function is implemented for TARGET(TPF) as a macro
that type casts its arguments, and therefore accepts mistyped arguments that
have the same bit patterns or arithmetic values as the required parameter
values. For ISO-C, wtopc is implemented as a function, so
the types of its arguments must match the documented interface.
TARGET(TPF) code that might execute correctly despite passing mistyped
arguments to wtopc will not compile for ISO-C. |
Examples
The following example sends a message to EBROUT with a header and without
chaining. The example uses the WTOPC_INSERT_HEADER macro.
#include <tpfapi.h>
·
·
·
struct wtopc_header header_buffer;
·
·
·
wtopc_insert_header(&header_buffer, "C000", 2, 'A', WTOPC_SYS_TIME);
wtopc("msg1", WTOPC_EBROUT, WTOPC_NO_CHAIN, &header_buffer);
·
·
·
The following example sends 2 messages to EBROUT and the PRIME CRAS,
chaining the 2 messages together and using the default header.
#include <tpfapi.h>
·
·
·
wtopc("msg2", WTOPC_EBROUT + WTOPC_PRC, WTOPC_CHAIN, NULL);
wtopc("msg3", WTOPC_EBROUT + WTOPC_PRC, WTOPC_CHAIN_END, NULL);
·
·
·
The following example sends 2 messages to EBROUT, chaining the 2 messages
together, using the default header and using the multi-page support.
#include <tpfapi.h>
·
·
·
rc = wtopc("msg2", WTOPC_EBROUT, WTOPC_PAGE, NULL);
if (rc == WTOPC_PAGE_STOP)
{
return(rc);
}
else
{
/* If it is WTOPC_NEXT_PAGE OR WTOPC_SUCCESS we would want to */
/* send the next line. */
wtopc("msg3", WTOPC_EBROUT, WTOPC_PAGE_END, NULL);
}
·
·
·
The following example sends a message to EBROUT and the PRIME CRAS using
the wtopc_routing_list macro and formatting the message using the
sprintf function. No header is requested.
#include <tpfapi.h>
·
·
·
long int rout_buffer;
char message_buffer[100];
char * s ="msg";
·
·
·
sprintf(message_buffer, "%s %d\n", s, 4);
wtopc_routing_list(rout_buffer, WTOPC_EBROUT + WTOPC_PRC);
wtopc(message_buffer, rout_buffer, WTOPC_NO_CHAIN, WTOPC_NO_HEADER);
·
·
·
The following example sends an unsolicited message to the terminal
specified in EBROUT and to RO solicited.
#include <tpfapi.h>
·
·
·
wtopc("msg5", WTOPC_UNSOL + WTOPC_EBROUT + WTOPC_RO, NULL, NULL);
·
·
·
Related Information