The ~$PWCG service is used to find some subset of the messages within a comgroup, and then optionally produce a report about them as wei I as optionally deleting or changing them. Usage of the informational (reporting) aspect of this service is restricted to users having AURD access to the comgroup. Usage of the operational (delete or change) aspect of this service is I imited to the AU of the comgroup.
The desired subset of messages is defined by the SCA, CRITERIA and QSELECT parameters.
If CRITERIA is NIL then one message is being selected, namely the currently-latched input message of the service call issuer. In this case DELETE and REATTR are ignored, that is the service becomes informational only. Note that such latched messages may only be viewed via ~$rwcG in this special way, that is to say the service cal I issuer can only 'see' his own latched input message by this special method, and can never see any other currently-latched messages.
Otherwise, that is when a VLP_CG~ is supplied as CRITERIA, QSELECT defines the
class(es) of messages being selected. The two classes are directed messages (i .e. those written to a specific station) and anonymous messages (i.e. those in the anonymous queue). QSELECT may be used to select either or both of these classes.
The VLP_CGMA framed by CRITERIA contains certain specifications for the attributes of the desired messages. The SCA parameter, framing a VLP_SCG~, defines which of these attributes are to be used in defining the desired subset. Thus, for example, to select messages written to stations whose names begin with 'ABC', one specifies QSELECT-DIRECT,
VLP_CG~.DEST='ABC?', and VLP_SCG~.DEST=YES, with all other options in VLP_SCG~ set to NO. To further qualify the subset and select only messages of type 'XYZ', one would also set VLP_SCG~.~GTYP to YES, and VLP_CG~.~SGTYP to 'XYZ'. Note that for the criteria ~GTYP, DEST, and ORIGIN, one may indicate don't-care (i .e. no restriction) in two ways, namely by setting the VLP_CGMA attribute to '?' and the VLP_SCG~ option to YES, or simply by setting the VLP_SCG~ option to NO.
Once the desired set of messages has been defined as described above, the function of the service must be specified. There are two aspects to this service: informational and operational.
The informational function returns the attributes of the messages found. This function takes two forms. First, the ONEATTR parameter, if specified, frames a VLP_CG~ area which is to receive the attributes of the first message found. This is most commonly used when a single message is expected, particularly in the case where CRITERIA is NIL (see above). The second form of information return, which may be specified in
conjunction with ONEATTR, is INFOR~. Setting INFOR~ to YES requests that the service build a special message containing a list with one entry for each message found, with each entry consisting of the attributes of the corresponding message. This special message wil I be sent to the service call issuer at the conclusion of the service call, and may subsequently be read at the issuer's discretion. Its message ID is returned into ~SGID in VLR_FWCG. See the discussion of the INFOR~ option for the specific structure of this message. Note that the size of the data of this special message depends on the number of messages found by the service, which is to say it may be very
large. The message may be read safely irrespective of size by specifying CONT on the M$READ. Note that INFOR~ requires the comgroup to have a value of at least 2 for the minimum number of data cache pages. If the minimum is less than 2, then ~$fWCG will
return on error.
The operational function 01 lows for deleting the selected messages or changing their attributes (called REATTR). These two choices are mutually exclusive. Specifically, the DELETE option is interrogated first; if DELETE is YES then the selected messages are deleted. If DELETE is NO, then the selected messages are changed if REATTR is
specified. Thus requesting the informational-only form of this service requires setting DELETE to NO and REATTR to NIL.
CE74-00 ~$fWCG - Find ~essages within a Comgroup 3-117
Changing the attributes of the selected messages is I imited by the fact that only one set of new attributes may be suppl ied. In other words, when REATTR is performed, all selected messages have their attributes changed in the same way. The set of attributes to be changed is defined by SRA which frames a VLP_SCGMA. The new values for these attributes are defined in REATTR which frames a VLP_CGMA. Thus. for example, to
redirect messages to a specific station, say 'ABC', one specifies YES fOi VLP_SCGMA.DEST (in SRA) , and 'ABC' for VLP_CGMA.DEST (in REATTR).
Once the attributes of a message have been changed, the message may have to be moved as a result. For example, if PRIO or UTS is changed then the message wi I I need to be moved to a different place in its original message queue. If DEST is changed then the message wi I I have to be moved to a different queue. Note in particular that if a non-blank DEST
is assigned to a message originally found in the anonymous queue, then the message leaves the anonymous queue and is placed in the queue of messages destined for the station whose name is in DEST. Note further that the REATTR operation is limited by the way in which the comgroup is defined. Thus assigning a new DEST of, say, 'ABC' wil I
cause the message to be deleted if station 'ABC' is not present and the comgroup does not al low writing to absent stations.
AU event messages (message type '.AUEV') may be deleted but may not have their
attributes changed. When a REATTR operation is being performed, the count of messages found and the INFOR~ result (if any) wil I include the AU event messages, but they wi II
be passed over during the REATTR phase.
Particular care must be exercised when changing the ~SGID. Under normal circumstances it is guaranteed that each message in the comgroup has a unique MSGID-MSGIDXT pair.
CP-6 fi Ie management makes little attempt to ensure that this wil I remain true when
~$FWCG is used to change the MSGID of a message. For further information, refer t~
MSGID in V LP_SCGMA, and to the section on 'REBUILDING A COMGROUP' in the general discussion of comgroups.
The form of the col I for this service is:
CALL ~$FWCG (FPT_fWCG) [ALTRET (label)];
The parameters are as fol lows:
CRITERIA
=
VARIABLE locates a VLP_CGMA area containing the selection criteria describing the desired messages. See also SCA.If CRITERIA is NIL, then the service is assumed to be selecting one specific message, namely the currently-latched input message associated with the DCB suppl ied with the service call. In this case, QSELECT is ignored; furthermore, DELETE and REATTR are
ignored, that is, the selected message is not affected in any way. Note that this is the only way in which such a latched message may be 'seen' via M$FWCG.
The default is NIL.
DCB - DCBN~E specifies the DCB associated with the comgroup.
DELETE - IVESINOI specifies whether (VES) or not (NO) the selected messages are to be deleted from the comgroup. If NO, then the REATTR option is honored if it is specified.
The default is NO.
INFORM
=
IVESINOI specifies whether (VES) or not (NO) a report is to be generated concerning the selected messages. If VES, then a special message wil I be created and sent to the station associated with the DCB supplied on the service call. This message has message type '.AUEV', and the first portion of the message data is structured as are al I such messages, that is, it is framed by the structure B$CGAURD. In particular, the B$CGAURO.EVENT word contains the value CG_FWCGI. The remainder of the message data consist. of a series of VLP_CGMA frames, one for each message found by the service, containing the attributes of those messages. The MSGID of this special message is returned in MSGID of VLR_twCG (see RESULTS). The default is NO.3-118 MSFWCG - Find Messages within a Comgroup CE74-00
ONEATTR
=
VARIABLE locates a VLP_CGMA area into which the attributes of the first message found are to be returned. Specification of ONEATTR has no effect or the action of INFORM. The default is NIL.QSELECT
=
OPTION is used in addition to CRITERIA to restrict the set of messagesselected. DIRECT specifies that only those messages destined for specific stations are to be considered. ANONYMOUS specifies that only messages in the anonymous queue are to be considered. ALL specifies that both classes of messages are to be considered.
QSELECT is only meaningful if CRITERIA is specified. The default is ALL.
REATTR
=
VARIABLE locates a VLP_CGMA area containing the new attributes to be given to the selected messages. REATTR appl ies only if DELETE is NO. and if specified. indicates that the REATTR function is to be performed. See also SRA. The default is NIL.RESULTS
=
VARIABLE locates a VLR_FWCG area into which certain result information wi I I be returned. The default is NIL.SCA
=
VARIABLE locates VLP_SCG~~ area containing a list specifying which of the attributes supplied in CRITERIA are actually to be used in selecting the desired messages. SCA must be specified if CRITERIA is specified. The default is NIL.SRA
=
VARIABLE locates a VLP_SCGMA area containing a list specifying which of the attributes supplied in REATTR are actually to to be used in changing the selected messages. SRA must be specified if REATTR is specified. The default is NIL.This macro generates an area which receives the results of M$FWCG.
FOUND
=
VALUE-DEC(0-n) is set to the number of messages found by the service.MSGID
=
VALUE-DEC(l-n) is set to the MSGID of the message generated when INFORM is specified as YES.This macro generates an area for use with M$FWCG. It contains a I ist of attribute flags used to select a subset of the attributes present in a VLP_CGMA area.
All of the flags are honored for SRA in M$FWCG. that is to say for REATTR. Only the following flags are honored for SCAt that is. for message selection criteria:
MSGTYP ORIGIN DEST MSGID MSGIDXT
DEST
=
IYESINOI selects (YES) or ignores (NO) the DEST attribute in the corresponding VLP_CGMA. The default is NO.DVE - IYESINO' selects (YES) or ignores (NO) the DVE attribute in the corresponding VLP_CGMA. The default is NO.
MSGID
=
IYESINO' selects (YES) or ignores (NO) the MSGID attribute in the corresponding VLP_CGMA.Note that if MSGID is YES for a REATTR function. then the current comgroup message 10 wil I be set to the supplied message 10 plus one if it is not already greater. This attempts to prevent dupl icate message IDs in the comgroup.
CE74-00 3-119
The default is NO.
MSGIOXT
=
VAlUE-OEC(0-6) selects (nonzero) or ignores (zero) the MSGIOXT attribute in the corresponding VlP_CGMA. MSGIOXT is only meaningful if MSGIO has been specified.For REATTR, that is to say in SRA, any nonzero value for MSGIOXT here causes the entire MSGIOXT in the selected message(s) to be changed to the MSGIOXT in the REATTR VlP_CGMA.
For message selection, that is to say in SCA, the meaning of MSGIOXT is somewhat
different. If the comgroup is using the second type of message 10 extension (see MSGIO in VlP_STATION) , then any nonzero value for MSGIOXT has the effect of selecting the entire MSGIOXT in VlP_CGMA.
On the other hand, if the comgroup is using the first type of message 10 extension, namely the six-level structure, then the MSGIOXT in CRITERIA may be wild-corded by appropriate setting of MSGIOXT here. When MSGIOXT is set to N, then the first N levels
in MSGIOXT in CRITERIA are used for message selection. For example, if the MSGIO in CRITERIA is 7, and the MSGIOXT in CRITERIA is 2-3-4-1-0-0, then setting MSGIOXT to 2 here causes a search for 01 I messages bearing MSGIO 7 and MSGIOXT 2-3-?-?-?-? VlP_CGMA permits the user to specify the various level values individually, as MIOXT1. MIOXT2 •
... • MIOXT6.
The default is zero.
MSGSIZE
=
IYESINOI selects (YES) or ignores (NO) the MSGSIZE attribute in the corresponding VlP_CGMA.Note that if MSGSIZE is YES for a REATTR function, then the size of the subject message may anly be reduced. not increased.
The default is NO.
MSGTYP
=
IYESINOI selects (YES) or ignores (NO) the MSGTYP attribute in the corresponding VlP_CGMA. The default is NO.ORIGIN = IYESINOI selects (YES) or ignores (NO) the ORIGIN attribute in the corresponding VlP_CGMA. The default is NO.
PRIO
=
IYESINOI selects (YES) or ignores (NO) the PRIO attribute in the corresponding VlP_CGMA.Note that if PRIO is YES for a REATTR function. then certain limits are placed on the legal values. For subject messages that are not AU event messages, the legal limits for PRIO in the VlP_CGMA are 0 to 256500. If the PRIO in VlP_CGMA is not legal, then no error wil I be reported; instead the highest possible legal value will be used.
The default is NO.
TYC = IYESINOI selects (YES) or ignores (NO) the TYC attribute in the corresponding VlP_CGMA. The default is NO.
UTS - IYESINOI selects (YES) or ignores (NO) the UTS attribute in the corresponding VlP_CGMA. The default is NO.
3-128 CE74-80
This macro generates an area for use with M$FWCG. It contains the attributes of a comgroup message. Those attributes which are honored in CRITERIA of M$FWCG are distinguished by the fact that they have default values.
DEST - VALUE-CHAR(8) is the destination of the message. If DEST is blanks, then the 'destination' of the message is the anonymous queue, otherwise DEST is the name of the specific station to which the message was written.
When suppl ied as part of CRITERIA to M$FWCG, DEST may be wi Id-carded. The default is '?', meaning that messages with any destination are desired. See also the QSELECT parameter of M$FWCG.
DVE is a collection of bits containing certain attributes of the message as a data record. The contents of DVE are not normally of interest to the issuer of M$FWCG other than as something to be received (as part of ONEATTR or INFORM), and supplied (as part of REATTR) when a message is being saved and reinserted.
MSGID = VALUE-OEC(l-n) is the comgroup message id of the message. Refer to the the discussion of MSGID under VLP_STATION.
When suppl ied as part of CRITERIA to M$FWCG, MSGID may be specified as zero to indicate that 01 I message IDs are desired.
The default is 0.
MSGIDBXT - VALUE-DEC(0-?) is the alias of MSGIDXT, for use when message 10 extensions take their second possible form. See MSGIDXT.
MSGIDXT - VALUE-BIT(36) is the extension to MSGID. Refer to the discussion of MSGID and MSGIDXT in VLP_STATION.
If MSGIDXT is to be suppl ied when this macro is invoked, it must be specified in its six component parts: MIDXT1, .... , , MIDXT6.
MSGIDXT.MIDXTl
=
VALUE-OEC(1-62) (See MSGIDXT).MSGIDXT.MIOXT2 = VALUE-OEC(1-62) (See MSGIDXT).
MSGIDXT.MIOXT3
=
VALUE-OEC(1-62) (See MSGIDXT).MSGIDXT.MIDXT4 - VALUE-OEC(1-62) (See MSGIDXT).
MSGIOXT.MIOXT5 - VALUE-OEC(1-62) (See MSGIDXT).
MSGIOXT.WIOXT6 - VALUE-OEC(1-62) (See MSGIDXT).
MSGSIZE - VALUE-OEC(0-n) is the size in bytes of the message.
MSGTYP - VALUE-CHAR(8) is the type of the message.
When supplied as part of CRITERIA to M$FWCG, MSGTYP may be wild-carded. The default is ' ? , meaning 01 I types are desired.
ORIGIN = VALUE-CHAR(8) is the name of the station which originated (wrote) the message.
When suppl ied as part of CRITERIA to M$PWCG, ORIGIN may be wild-carded. The default is '?'. meaning messages with any origin are desired.
PRIO - VALUE-OEC(0-262143) is the message priority. Priorities of normal messages lie in the range 1 through 256000. However, some special messages (generated by the comgroup itself), notably the AU event messages, have priorities outside this range.
CE74-00 3-121
TYC - VAlUE-BIT(36) is a collection of bits to be passed as a TYC value to the eventual reader of the message. See the discussion of TYC under M$OCB. TYC is simi lar to DVE in that it is not normally of interest other than as a field to be received and supplied.
UTS - VAlUE-DEC(&-n) is the system time stamp (in UTS format) of the time at which the
~.llage was created.
3-122 CE74-8e