WTO

WTO

Write to Operator

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
IMPLEMENTATION
EXAMPLES
RELATED FUNCTIONS

SYNOPSIS

#include <oswto.h>
int WTO(char *msg, ...);

DESCRIPTION

The WTO function implements the functionality of the OS/390 assembler WTO macro. The msg argument is the address of a null-terminated string, or in the case of a multi-line message, this argument should be set to 0 . The remainder of the argument list is a list of keywords followed, in most cases, by an argument specifying a value for the keyword. The list is terminated by the _Wend keyword. The supported keywords and their associated data are as follows:

The _Wctext keyword is equivalent to the Assembler TEXT=(msg,C) , which identifies the first line of a multi-line message as a control line. The next argument should be a null-terminated string containing the text to be displayed. If coded, this must be the first text type of keyword and can only be specified once. For this and the following text arguments, the first argument to WTO , msg , must be 0 to indicate a multi-line rather than a single-line message.
The _Wltext keyword is equivalent to the Assembler TEXT=(msg,L) , which identifies a label line of a multi-line message. The next argument should be a null-terminated string containing the text to be displayed. This argument, if coded, must follow the _Wctext argument and precede any _Wtext arguments. There can be a maximum of 2 label lines.
The _Wtext keyword is equivalent to the Assembler TEXT=(msg,D) , which identifies a detail line of a multi-line message. The next argument should be a null-terminated string containing the text to be displayed. Up to 10 detail lines can be output, however if control or label lines are also to be sent, the total number of lines is still limited to 10.
The _Wroutcde keyword is equivalent to the Assembler ROUTCDE keyword. The next argument(s) should consist of one or more integers representing routing codes in the range of 1-28.
The _Wdesc keyword is equivalent to the Assembler DESC keyword. The next argument(s) should consist of one or more integers representing descriptor codes in the range of 1-13.
The _Wresp keyword is equivalent to the Assembler MCSFLAG(RESP) keyword, indicating that the WTO is an immediate command response.
The _Wreply keyword is equivalent to the Assembler MCSFLAG(REPLY) keyword, indicating that this WTO is a reply to a WTOR .
The _Wbrdcst keyword is equivalent to the Assembler MCSFLAG(BRDCST) keyword, used to broadcast the message to all active consoles.
The _Whrdcpy keyword is equivalent to the Assembler MCSFLAG(BHRDCPY) keyword, indicating to queue the message for hard copy only.
The _Wnotime keyword is equivalent to the Assembler MCSFLAG(NOTIM) keyword, indicating that the time should not be appended to this message.
The _Wcmd keyword is equivalent to the Assembler MCSFLAG(CMD) keyword, indicating that the WTO is a recording of a system command issued for hardcopy log purposes.
The _Wbusyexit keyword is equivalent to the Assembler MCSFLAG(BUSYEXIT) keyword, indicating that if there are no message or console buffers, the WTO is not to go into a wait state.
The _Wcart keyword is equivalent to the Assembler CART keyword. The next argument should be the address of an 8-byte field containing a command and response token to be associated with this message.
The _Wkey keyword is equivalent to the Assembler KEY keyword. The next argument should be the address of an 8-byte key to be associated with this message.
The _Wtoken keyword is equivalent to the Assembler TOKEN keyword. The next argument should be an unsigned long integer representing the token to be associated with this message. This is used to identify a group of messages that can be deleted by the DOM_TOK() function. The token must be unique within an address space.
The _Wconsid keyword is equivalent to the Assembler CONSID keyword. The next argument should be an unsigned long integer containing the id of the console to receive the message. This argument is mutually exclusive with _Wconsname .
The _Wconsname keyword is equivalent to the Assembler CONSNAME keyword. The next argument should be the address of an 8-byte field containing a 2 through 8 character name, left-justified and padded with blanks naming the console to receive the message. This argument is mutually exclusive with _Wconsid .
The _Wmsgid keyword is to pass back a message identification number if the WTO is successful. The next argument should be the address of an unsigned long variable which will be filled in after the WTO completes. This number can then be used to delete the WTO with the DOM() function.
The _Wend keyword indicates the end of the list of keywords.

RETURN VALUE

WTO returns 0 if the WTO macro was successful. If the WTO macro fails, it returns the return code from the macro, which will be a positive value. WTO may also return -1 to indicate an unknown or invalid keyword combination, or -2 if there was not enough memory to perform the WTO .

IMPLEMENTATION

The WTO function is implemented by the source module L$UWTO . As a convenience, the macro WTP can be used for single line messages used by programmers. It is defined as follows:

#define WTP(msg) WTO(msg, \
                     _Wroutcde, 11, \
                     _Wdesc, 7, \
                     _Wend);

EXAMPLES

EXAMPLE 1:

This example uses the WTP macro to send two single-line programmer's messages:

#include <oswto.h>

char msg[120];
int iLine;

iLine = 20;
sprintf(msg, "Error discovered at line: 
        %i", iLine);
WTP(msg);
WTP("Aborting...");

EXAMPLE 2:

This example sends a multi-line message to a specific console.

#include <oswto.h>
#include <code.h>
#include <genl370.h>

int regs[16];
char line1[50];
char line2[50];
char line3[50];
char line4[50];

_ldregs(R1, regs);

/* save current registers 
   in the regs array */
STM(0,15,0+b(1));

sprintf(line1,
   "GPR  0-3  %08X  %08X  %08X  %08X",
   regs[0], regs[1], regs[2], regs[3]);

sprintf(line2,
   "GPR  4-7  %08X  %08X  %08X  %08X",
   regs[4], regs[5], regs[6], regs[7]);

sprintf(line3,
   "GPR  8-11 %08X  %08X  %08X  %08X",
   regs[8], regs[9], regs[10], regs[11]);

sprintf(line4,
   "GPR 12-15 %08X  %08X  %08X  %08X",
   regs[12], regs[13], regs[14], regs[15]);

WTO(0, _Wctext, "XXX99999",
       _Wtext, "Register contents:",
       _Wtext, line1,
       _Wtext, line2,
       _Wtext, line3,
       _Wtext, line4,
       _Wconsname, "CONSOLE1",
       _Wroutcde, 11, 
       _Wdesc, 7, 
       _Wend);

RELATED FUNCTIONS

DOM , DOM_TOK , WTOR

Chapter Contents
Previous
Next
Top of Page