gtpc2m9qC/C++ Language Support User's Guide

wtopc-Send System Message

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

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