|
|
|
Writes the specified text.
&WRITE [ ALARM={ YES | NO } ]
[ ALL={ YES | NO } ]
[ COLOR=color | COLOUR=colour ]
[ CR={ YES | NO } ]
[ FF={ YES | NO } ]
[ HLIGHT=hlight | HLITE=hlight ]
[ INTENS={ HIGH | NORMAL } ]
[ LF={ YES | NO } ]
[ LOG={ YES | NO } ]
[ { MDO=mdoname |
ARGS [ RANGE=(start, end) ] |
VARS={ var | ( var1, var2, ..., varn) } } ]
[ TYPE={ REQUEST | RESPONSE } ]
[ MON={ YES | NO } ]
[ MSGCODE=xx ]
[ NRD={ YES | NO | OPER } ]
[ RC={ (n,n,...,n) | ALL | NONE } ]
[ SCAN={ YES | NO } ]
[ TERM={ YES | NO } ]
[ USERID=userid | LUNAME=luname | NCLID=nclid | SERVER=servername ]
[ AOM={ YES | NO } ]
[ AOMAUTH=[ YES | NO ]
[ AOMID=identifier ]
[ AOMJOBID=jobid ]
[ AOMJOBNM=jobname ]
[ AOMMINOR={ YES | NO } ]
[ AOMMSGID=msgid ]
[ AOMMSGLV={ IN | msglevel } ]
[ AOMRC= | ROUTCDE= | RC={ 2 | NONE | ALL | list } ]
[ AOMSOS={ OS | VM } ]
[ AOMTIME=hhmmss ]
[ AOMTYPE={ WTO | WTOR | MSG } ]
[ AOMUFLGS=nn | AOMUFLGn={ YES | NO } ]
[ AOMUSERI=userid ]
[ AOMUSERN=usernode ]
[ DATA=message-text ]
The &WRITE verb lets an NCL procedure issue a message. By default, the message is sent to the environment in which the NCL procedure is executing.
Several operands allow the message to be sent to MONITOR class OCS users, all OCS users, and so on. Other operands allow setting of message attributes, such as color and alarm. Automation Services adds several additional operands, that allow assignment of AOM routing options, and AOM attributes.
Operands:
The following operands are available to all users for message attribute assignment and message routing. AOM-specific operands follow these.
Specifies whether the message is to ring the terminal alarm when displayed on an OCS window.
specifies that the message is to be written to all OCS users and dependent environments profiled to receive general broadcast messages.
The color in which the message is to be displayed. This is ignored if the terminal does not support extended color data streams. Color must be one of the following:
RED GREEN BLUE TURQUOISE YELLOW PINK WHITE NONE
Indicates, for LU1 type terminals, whether a carriage return function is to be performed after writing the specified text. CR=YES, the default, indicates that carriage return is required, CR=NO that it is not.
Indicates, for LU1 type terminals, whether a form feed function is to be performed. The form feed is actioned before any supplied text is written to the device. If no text is supplied, a blank line will be written after the form feed is actioned, unless LF=NO is also specified.
The extended high-lighting in which the message is to be displayed. This is ignored if the terminal does not support extended high-lighting data streams. hlight must be one of the following:
REVERSE USCORE BLINK NONE
Specifies whether the message is to be displayed on the terminal in high or normal intensity.
Indicates, for LU1 type terminals, whether a line feed function is to be performed after writing the specified text. LF=YES, the default if the LF operand is not specified, indicates that a line feed function is required, LF=NO that it is not. LF=NO is used to create a strike-over mask so that secure data is entered on the terminal. Two or three successive &WRITE statements with LF=NO, followed by an &PROMPT statement, will effectively obliterate the entered data. The LF operand is ignored if used to write a message to a terminal that is not an LU1.
LOG=YES specifies that the message is to be written to the activity log.
MDO=mdoname specifies a mapped data object (MDO) to be delivered to the target destination. The MDO will be embedded in the $MSG user MDO and the $MSG.MAPNAME element set to the stem MAP name.
Specifying VARS or ARGS results in a $NCL MDO being built and delivered in the $MSG MDO, containing the named variables or arguments.
Notes: The MDO, VARS, and ARGS operands are mutually exclusive.
RANGE=(start, end) is specified with ARGS to denote an argument range.
This operand allows messages to be written to the target's request queue or response queue. The default is the response queue. For TYPE=REQUEST, the target must be another NCL procedure.
Specifies that the message is to be written to all OCS users and dependent environments profiled to receive Monitor class messages.
Supplies a two digit hex message delivery code. This value is used as an 8-bit mask matched against the profile of possible receiving environments. Its use implies ALL=YES as the default generic delivery option but is overridden by supplying other options such MON=YES, FTS=YES and so on. An OR comparison is used and delivery is initiated when at least one or more bits are matched. Thus the value is equivalent to an 8-bit routing code.
The message delivery code facility allows the installation to develop and control delivery of messages in a variety of classes designed to meet the needs of the installation.
Specifies whether the message is to be classified as non-roll delete, that is, whether it will remain on the operator's window until deleted rather that being rolled over by other messages as they arrive. If NRD=NO is coded, or allowed to default, the message will be a standard roll-delete message.
If NRD=YES is coded, the message is assigned a delete operator message identifier or DOM ID. The value of the DOM ID is returned on completion of the &WRITE in the &ZDOMID system variable. If the message is to be deleted at some future time, this DOM ID must be specified as an operand on a &NRDDEL statement. The NRD message will also be deleted when the NCL process that issued the &WRITE statement terminates.
If NRD=OPER is coded the message is classified as non-roll delete but no DOM ID is assigned to it and it will never be deleted by any means except NRD cursor deletion - even when the originating process terminates.
Specifies the routing codes to be used to determine the delivery of the message. Use of this operand is supported only if products that include Automation Services are installed. Receivers must have a match on any of the nominated route codes (n) to qualify for receipt of the message. RC=NONE will deliver the message to all AOM receivers who have at least one routing code active.
Indicates that the message can contain strings of characters, delimited by @s, meaning that the delimited string should be highlighted at the terminal. A scan of the message takes place and the @s removed, being replaced by the appropriate attribute settings to turn highlighting on and off at the terminal.
TERM=YES specifies that the message is to be written to the owning environment. In the case of an NCL process executing directly from OCS the message will appear on the user's OCS window. Line messages issued under a full-screen process, for example, User Services, will not be displayed until the full screen process terminates.
Messages issued from system procedure environments, such as LOGPROC, AOMPROC, PPOPROC and so on. will be treated as monitor class messages and will be generically delivered with an identifying character prefixing the text. For example, messages from LOGPROC are delivered to all monitor receivers with L as the prefix.
By default, messages issued from BSYS and BLOG background environments are directed to the log. Messages from BMON are treated as specifying MON=YES.
TERM=NO specifies that the message will not be delivered to the target response queue.
TERM=NO is mutually exclusive with the SERVER, USERID, LUNAME and NCLID operands.
Specifies that the message is to be written to the specified user ID only. On completion, &RETCODE is set.
Indicates the node name of the terminal to which the message is to be sent. The terminal is either an LU1 terminal or a terminal with an OCS window(including the CONSOLE device).
Specifies that the message is to be delivered to a dependent queue of the nominated process.
This operand allows the messages to be directed at a registered server procedure.
The text of the message to be displayed at the terminal, written to an LU1 device or written to the activity log. Normal variable substitution will be performed before sending the message. Text is in upper and lower case. If no text is supplied, a blank line will be displayed or written (unless LF=NO is specified for LU1). DATA can only be specified as the last keyword on the statement since the data string is regarded as being everything to the right of the DATA= keyword to the end of the statement.
These are the AOM-specific operands and are available only in regions that include Automation Services products. The preceding operands are available to all users.
Note: Where defaults are shown for AOM attributes, they apply only if any AOM attributes are specified. If no AOM attributes are specified, no AOM attributes are carried with the message.
Indicates whether the message is to be routed to all authorized AOM message receivers or not.
AOM=NO (the default) means no AOM specific delivery will take place. Other &WRITE operands such as MON= can cause delivery to more than one user. In this case, other AOM operands is coded, to give the message AOM attributes without causing automatic AOM delivery.
AOM=YES will cause the message to be delivered to authorized AOM receivers.
If no AOM attributes are specified, all AOM receivers will receive the message irrespective of profiled routing codes and AOM message levels. If any other AOM attributes are specified, the message will be delivered to AOM receivers based on user profile routing codes and message levels (that is at least one message level in common, and at least one route code in common, except that BC message level bypasses routing codes, and if the message has ROUTCDE=NONE, then that matches any user profile ROUTCDE except NONE).
A prefix of A is attached to all AOM messages produced by &WRITE, except those sourced by NCL procedures in the AOMP environment that also have AOM attributes specified.
Allows setting of the AOM authorized issuer attribute. This attributes indicates whether the original issuer of the message (WTO) was MVS-authorized. This attribute is available after &MSGREAD or &INTREAD in the &ZMAOMAU system variable.
Assigns the AOM ID attribute. identifier must be null, or from 1 to 12 characters in length. This value is available after &MSGREAD or &INTREAD in the &ZMAOMID system variable.
Assigns the AOM JOBID attribute. jobid must consist of the job type, either J, S, or T, and a 1 to 5 digit number. This value is available after &MSGREAD or &INTREAD in the &ZMAOMJI system variable.
This attribute implies a source operating system of OS. Thus, it is invalid with any VM attributes or AOMSOS=VM.
Assigns the AOM JOBNAME attribute. jobname must be null, or from 1 to 8 characters. This value is available after &MSGREAD or &INTREAD in the &ZMAOMJN system variable.
This attribute implies a source operating system of OS. Thus, it is invalid with any VM attributes or AOMSOS=VM.
Indicates whether this message is a minor line. Minor lines are not subject to AOM prefixing. Normally, this is used for multi-line displays, where only the first line needs AOM prefixes. The value of this attribute is available after &MSGREAD or &INTREAD in the &ZMAOMMIN system variable.
This attribute implies a source operating system of OS. Thus, it is invalid with any VM attributes or AOMSOS=VM.
Assigns the AOM message ID attribute. msgid must be null, or from 1 to 12 characters. This value is available after &MSGREAD or &INTREAD in the &ZMAOMMID system variable.
Assigns the AOM message level attribute. The default, INformational, only applies if any AOM attributes are specified.
If AOM=YES is also specified, the AOM message level is used to determine which authorized AOM receivers will receive a copy of the message.
Allows specification of a list of routing codes. Routing code values are from 1 to 128. The default, 2, only applies if any AOM attributes are specified.
If AOM=YES is also specified, these routing codes will be used to determine which AOM receivers will receive a copy of the message. Receivers with at least one routing code in common, or, if ROUTCDE=NONE is specified, receivers with at least one routing code, receive the message (subject to MSGLEVEL screening).
A single value is specified as AOMRC=n. Multiple values, and ranges is specified as:
ROUTCDE and RC are alternative spellings of this parameter.
The value of this operand is available in the &ZMAOMRC system variable after &INTREAD or &MSGREAD.
Allows explicit setting of the AOM source operating system attribute. The default is the operating system that this product region is executing under, unless an AOM operand that implies a specific operating system is specified.
Attributes that imply a specific source operating system are marked. Use of these operands must be consistent with the value specified for AOMSOS if coded.
The value of this operand is available after &MSGREAD or &INTREAD in the &ZMAOMSOS system variable.
Allows a specific AOM message time to be set. The default, if this parameter is omitted, is the current time. hhmmss must be 6 digits, in the range 000001 to 240000.
Allows setting of a specific AOM message type. The default value for this operand depends on the operating system, or specified AOMSOS value. If z/OS, then AOMTYPE=WTO is assumed. If z/VM, AOMTYPE=MSG is assumed.
The value of this attribute is available after &MSGREAD or &INTREAD in the &ZMAOMTYP system variable.
Specification of this attribute can imply a specific source operating system. This can cause an error if incompatible operating system related attributes are specified.
Allows setting the 8 AOM user flag attributes. All 8 is set as a hexadecimal value, using the AOMUFLAGS=nn operand, or the flags is set individually, using AOMUFLGn=YES/NO.
The values of these flags are available after &INTREAD or &MSGREAD in the &ZMAOMUFn system variables.
Assigns the AOM USERID attribute. userid must be null, or from 1 to 8 characters. This value is available after &MSGREAD or &INTREAD in the &ZMAOMUI system variable.
This attribute implies a source operating system of VM. Thus, it is invalid with any VM attributes or AOMSOS=OS.
Assigns the AOM USERNODE attribute. usernode must be null, or from 1 to 8 characters. This value is available after &MSGREAD or &INTREAD in the &ZMAOMUN system variable.
This attribute implies a source operating system of VM. Thus, it is invalid with any VM attributes or AOMSOS=OS.
The text of the message to issue. Maximum length of the message is 256 characters. This is a standard &WRITE operand.
Examples: &WRITE
&WRITE TEST MESSAGE
&WRITE ALARM=YES COLOR=RED HLITE=REVERSE DATA=ring the +
alarm
&WRITE MON=YES LOG=YES DATA=Message to all Monitors and +
to the log.
&WRITE LOG=YES TERM=NO DATA=message to the log only
&WRITE FF=YES LUNAME=PRINTER1 DATA=Network Report ----- +
Page No: &PAGE
&WRITE FF=YES LF=NO
&WRITE SCAN=YES DATA=RELOAD@NCP23@NOW
AOM Examples:
&WRITE COLOR=RED AOM=YES DATA=AOM IS ALIVE
&WRITE USERID=U1234 AOMJOBNM=JOB1 DATA=job1 related msg
Note: When using &WRITE it is good practice to always include DATA= before the message text to differentiate between the message text and other operands. For example,
&WRITE DATA=RC=(&RETCODE)
rather than
&WRITE RC=(&RETCODE)
as RC would be interpreted as the ROUTCDE operand in the latter.
Notes:
Messages written using &WRITE ALARM=YES and &WRITE MON=YES are by default logged unless overridden by the LOG= operand.
Generic delivery options such as MON=YES, FTS=YES is used to broadcast to OCS operators and dependent environments. Dependent environments are by default set to a profile that disallows any generic message receipt. Use of &INTCMD PROFILE MONMSG=YES, and so on, allows the dependent environment to be used for unsolicited message receipt.
Messages generated to primary environments is processed by a MSGPROC before further processing or display. The MSGPROC associated with the primary environments of system procedures, for example, LOGPROC, is used to process messages before their generic delivery as monitor messages with an identifying prefix.
The use of ALL=YES either explicitly or implicitly via MSGCODE= without other generic delivery options is equivalent to the use of the MSG ALL command. The receipt of these messages is controlled by the PROFILE MSG=Y | N of the receiving environment.
If variables are used to provide the message text, the contents of the variables is hexadecimal data.
Alarm, high-intensity, NRD, and routing code options are ignored for LU1 type terminals.
&WRITE with AOM operands is similar to &AOMALERT ROUTE=MSG. However, &WRITE allows sending the message to a specific user, by using the LUNAME, USERID, and NCLID operands. &AOMALERT does not allow this.
If NRD=YES is specified, the system variable &ZDOMID contains the assigned message DOMID, in the format domain/n. This value is used in a subsequent &NRDDEL verb to delete the message.
Note: See also the PROFILE command used to control an environment's message receipt options in the Online Help.
Return Codes:
When one of the target operands of the &WRITE verb is specified (that is, LUNAME, NCLID, SERVER, or USERID), &RETCODE is set as follows:
The message was delivered to the specified destination.
The target was a closed OCS window.
The LUNAME specified was not available.
The USERID or LUNAME specified was not in OCS mode.
The target was not found in the System Services domain.
The destination procedure was at queue limit, or the storage limit was reached.
The target for a TYPE=REQ request was not an NCL procedure.
The contents of the source MDO exceeds the maximum allowable size.
| Copyright © 2009 CA. All rights reserved. |
|