SAS/C Software: Changes and Enhancements, Release 6.50

New (Non-OpenEdition) Library Functions

This section describes the changes and enhancements to additional (Non-OpenEdition) SAS/C Library Functions for Release 6.50.

DOM

Delete Operator Message

SYNOPSIS

 #include <oswto.h>
void DOM(int iMsg);

DESCRIPTION

The DOM function implements the functionality of the MVS assembler DOM macro. This function is used to delete an operator message from the display screen of the operator's console. It can also prevent messages from ever appearing on any operator's console. When a program no longer requires that a message be displayed, it can issue the DOM function to delete the message. The iMsg argument is returned as a fullword from the WTO or WTOR function, which has been coded with the _Wmsgid keyword.

RETURN VALUE

There is no return value from the DOM function.

IMPLEMENTATION

The DOM function is implemented by the source module L$UWTO.

EXAMPLE

This example uses the DOM function to delete an operator message.

  #include <oswto.h>

 int iMsg;

 WTO("Experiencing storage shortage", 
     _Wmsgid &iMsg, _Wend);
          .
          .
          .
 /* delete msg from console */
 DOM(iMsg);

RELATED FUNCTIONS

DOM_TOK, WTO, WTOR

DOM_TOK

Delete Operator Message (using token)

SYNOPSIS

 #include <oswto.h>
void DOM_TOK(int iMsg);

DESCRIPTION

The DOM_TOK function implements the functionality of the MVS assembler DOM macro. This function is used to delete an operator message from the display screen of the operator's console. It can also prevent messages from ever appearing on any operator's console. When a program no longer requires that a message be displayed, it can issue the DOM_TOK function to delete the message. The iMsg argument is same as the fullword supplied to the WTO or WTOR functions using the _Wtoken keyword.

RETURN VALUE

There is no return value from the DOM_TOK function.

IMPLEMENTATION

The DOM_TOK function is implemented by the source module L$UWTO.

EXAMPLE

This example uses the DOM_TOK to delete an operator message.

  #include <oswto.h>

 int iMsg;

 WTO("Experiencing storage shortage", 
     _Wtoken 12345, _Wend);
          .
          .
          .
 /* delete msg from console */
 DOM_TOK(12345);

RELATED FUNCTIONS

DOM, WTO, WTOR

WTO

Write to Operator

SYNOPSIS

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

DESCRIPTION

The WTO function implements the functionality of the MVS 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

WTOR

Write to Operator with Reply

SYNOPSIS

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

DESCRIPTION

The WTOR function implements the functionality of the MVS assembler WTOR macro. The msg argument is the address of a null-terminated string. 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 listed under the WTO function with the addition of the following:

The _Wreplyadr keyword is to pass back the operator reply. The next argument should be the address of an area which will be filled in after the WTOR completes. This area can be from 1 to 119 bytes in length.
The _Wreplylen keyword is used to indicate the length of the _Wreplyadr area. The next argument should be an unsigned character variable containing an integer in the range of 1 to 119.
The _Wecb keyword is used to identify an ECB to be POSTed when the WTOR has received a response. The next argument should be a pointer to a fullword, which is the ECB to be POSTed.
The _Wreplycon keyword is equivalent to the Assembler RPLYISUR keyword. The next argument should be the address of a 12-byte field where the system will place the 8-byte console name and the 4-byte console id of the console through which the operator replies to this message.

RETURN VALUE

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

IMPLEMENTATION

The WTOR function is implemented by the source module L$UWTO.

EXAMPLE

This example uses the WTOR to request some information from the operator. The program then waits for a response and then writes the response back to the operator console.

 #include <oswto.h>
#include <ostask.h>

int msgid;
unsigned int uiEcb;
unsigned char ucConsoleName[13] 
                      = "            ";
unsigned char ucOperatorReply[71];
memset(ucOperatorReply, ' ', 70);
WTOR("Enter password:",
     _Wreplyadr, ucOperatorReply,
     _Wreplylen, 70,
     _Wecb, &uiEcb,
     _Wreplycon, ucConsoleName,
     _Wtoken, 12345,
     _Wend); 
ucOperatorReply[70] = 0;
ucConsoleName[8] = 0;
WAIT1(&uiEcb);
WTO(0, _Wctext, "XXX99999",
    _Wtext, "Operator at console:",
    _Wtext, ucConsoleName,
    _Wtext, "replied:",
    _Wtext, ucOperatorReply,
    _Wroutcde, 11, 
    _Wdesc, 7, 
    _Wend);

RELATED FUNCTIONS

DOM, DOM_TOK, WTO

Chapter Contents
Previous
Next
Top of Page