General
Application area: | Eventing; see "Eventing" |
Macro type: | Type S, MF format 1: standard/L/E form; see "S-type macros" |
In the event of macro chaining, all the macros chained must make use of the same interface. If the 24-bit interface is used, a 4-byte field is generated for the post code. If the 31-bit interface is used, the post code may have a length of either 4 or 8 bytes.
Macro description
This macro is used to indicate to the event item that an event has occurred. The event item must previously have been assigned to the task of the calling program (by calling the ENAEI macro).
The program which issued the POSSIG macro is always continued. It can also specify a contingency process, which is initiated as soon as POSSIG satisfies a “SOLicit SIGnal request” (SOLSIG) or as soon as a prescribed period of time has elapsed. This contingency process provides information on whether or not the signal was used within this period of time.
The contingency process must already have been defined (by ENACO).
Macro format and description of operands
POSSIG |
{ {EINAME=name / EINAMAD={addr / (r)}[,EINAMLN=length]} ,SCOPE={LOCAL / GROUP / USER_GROUP / GLOBAL} / EIID={addr / (r)} } [, {SPOSTAD={addr / (r)} / SPOSTR=r}],SPOSTL=1/ 2 [,LIFETIM=sec / (r)] ,CONTINU=NO / YES / SOLSIG [,COID=addr / (r)] [,COMAD=addr / (r)] [,PARMOD=24 / 31] [,MF=L / (E,..)] |
EINAME=name
Specifies the name of the event item to which the event is to be signaled. The event item must previously have been defined by the ENAEI macro. The name of the event item is unique only if SCOPE is also specified.
EINAMAD=
Specifies the address of the name of the event item. This entry is unique only if SCOPE is also specified.
addr
Symbolic address of the field containing the name.
(r)
Register containing the address.
EINAMLN=
Specifies the length in bytes of the event item name. If the operand is missing, the length attribute of the EINAMAD operand is assumed if EINAMAD=addr is specified;
if EINAMAD=(r), the maximum length (54 bytes) is assumed.
length
Length of the event item name.
SCOPE=
Specifies the scope of the event item (i.e. participants authorized to use it).
LOCAL
The use of the event item is limited to the calling task.
GROUP
All the tasks with the same user ID as the calling task are participants.
USER_GROUP
All the tasks, whose user IDs belong to the same user group as the user ID of the creating participant, can be participants.
The operand value assumes the existence of user groups and may therefore only be specified when the SRPM function unit of the SECOS software product is available in the system. This is why the GETUGR macro (see the “SECOS” manual [14 (Related publications)]) has to check whether SRPM is available prior to a macro call with SCOPE=USER_GROUP; the program reaction is dependent on the result (return code).
GLOBAL
All the tasks in the system are participants.
EIID=
Specifies the ID of the event item. The ID is supplied to the user by the ENAEI macro call. If the ID is used instead of the name to identify the event item, it speeds up processing. The ID is unique.
addr
Symbolic address of a 4-byte field containing the event item ID.
(r)
Register containing the address of the field.
MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. for a prefix), see section “S-type macros”. The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.
PARMOD=
Controls macro expansion. Either the 24-bit or the 31-bit interface is generated.
If PARMOD is not specified here, macro expansion is performed according to the specification for the GPARMOD macro or according to the default setting for the assembler (= 24-bit interface).
24
The 24-bit interface is generated. Data lists and instructions use 24-bit addresses (address space <= 16 Mb).
31
The 31-bit interface is generated. Data lists and instructions use 31-bit addresses (address space <= 2 Gb).
SPOSTAD=
Specifies the field containing the post code information to be transferred to the corresponding program (which issues the SOLSIG macro) (see section “Eventing”). The post code has a length of either 4 or 8 bytes.
It is also transferred to the contingency process, if present (COID operand). Post code
X'00000000' is not transferred.
Processing is speeded up if SPOSTR, which offers the same function, is used instead of SPOSTAD.
addr
Symbolic address of the field containing the post code information.
Length = 4 or 8 bytes.
(r)
Register containing the address value “addr”.
SPOSTR=
Specifies a register containing the post code information to be transferred to the corresponding program (which issues the SOLSIG macro).
If the 8-byte post code (= 2 words) is used, the register following the specified register (in number) must contain the 2nd word of the post code. Post code X'00000000' is not transferred.
(r)
Register containing the post code. Registers R0 and R1 should not be used.
SPOSTL=
Gives the length of the post code in words. If the 24-bit interface (PARMOD=24) is used, only SPOSTL=1 is permitted.
1
The post code is 1 word (4 bytes) long.
2
The post code is 2 words long.
LIFETIM=
Specifies the time for which the signal is to be used by a corresponding SOLSIG request. The event information code informs the contingency process, if any, whether or not the signal was used within this period of time.
sec
Time in seconds. 1 <= sec <= 43200
The processing accuracy for this operation is +10 seconds.
Default value: 600 sec.
(r)
Register containing the time specification in seconds.
CONTINU=
Permits POSSIG macro chaining with further POSSIG macros or with a SOLSIG macro. All macros chained must make use of the same interface.
NO
No further POSSIG or SOLSIG macro immediately follows the POSSIG macro.
YES
A further POSSIG macro immediately follows a POSSIG macro.
SOLSIG
A SOLSIG macro immediately follows the POSSIG macro.
Operands used to specify a contingency process
COID=
Specifies the ID of the contingency process. The ID is supplied to the user by the ENACO macro.
addr
Symbolic address of the field containing the ID.
(r)
Register containing the address value “addr”.
COMAD=
Specifies a contingency message. This contingency message is passed to the contingency process (register R1). A message issued here replaces any message that might have been issued when the contingency was defined (see section “Contingency processes”).
addr
Symbolic address of a word containing a contingency message.
(r)
Register containing the address.
Notes on the macro call
The POSSIG queue of an event item cannot accept an unlimited number of requests. In order to protect the system, the number of POSSIG requests in the queue of an event item is limited to a machine-dependent maximum value.
If a program (package) has defined a contingency process that is written in SPL, register 12 must contain the address of the SPL program manager for all ENACO, SOLSIG and POSSIG calls.
Return information and error flags
During macro processing, register R1 contains the operand list address.
R15:
+---------------+ | | | | | |b|b| | | | |a|a| +---------------+
A structured return code (aa = primary return code,
bb = secondary return code) relating to the execution of the POSSIG macro is transferred in register R15.
X'bb' | X'aa' | Meaning |
X'00' | X'00' | Function executed: the signal was successfully sent |
X'0C' | X'04' | No action: the event item established by the system was not assigned to the task |
X'10' | X'04' | No action: invalid operands were specified |
X'14' | X'04' | No action: invalid name or ID. An event item with the specified name does not exist |
X'18' | X'04' | No action: the maximum number (400) of contingency processes permitted per |
X'24' | X'04' | No action: invalid contingency ID. No contingency process with this ID exists |
X'28' | X'04' | No action: the maximum number of requests in the POSSIG queue was reached |
The following applies to macro chaining (CONTINU operand):
aa = X'00' aa = X'04' | All macro calls in the chain were completed. A macro in the chain was not completed (all preceding macros in the chain |
Information on post code usage is supplied on "Eventing".
The various meanings of the event information code values for contingency processes are described in table 7 (Contingency processes).
Example
POSSIG START
PRINT NOGEN
POSSIG AMODE ANY
GPARMOD 31
1 *,MACRO: GPARMOD, VERSION: VER121
BALR 5,0
USING *,5
ENAEI EINAME=EVENT,SCOPE=GROUP,EIIDRET=KKEV ———————————————— (1)
POSSIG EIID=KKEV ——————————————————————————————————————————— (2)
ST 15,RCFIELD1
ENACO CONAME=CONT,COADAD=COANFAD,COIDRET=KKCO —————————————— (3)
POSSIG EIID=KKEV,COID=KKCO,LIFETIM=60 —————————————————————— (4)
ST 15,RCFIELD2
LOOP CLI SWITCH,'0'
BE LOOP
ST 2,ACKNO —————————————————————————————————————————————— (5)
DISCO COID=KKCO
ST 15,RCFIELD3
DISEI EIID=KKEV
ST 15,RCFIELD4
DTH1 TERM
COANF BALR 6,0
USING *,6
CONTXT STACKR=(2),OWNR=(2),FUNCT=WRITE ————————————————————— (6)
MVI SWITCH,'1'
RETCO
KKEV DS F
KKCO DS F
COANFAD DC A(COANF)
SWITCH DC C'0'
*
ACKNO DS F
RCFIELD1 DS F
RCFIELD2 DS F
RCFIELD3 DS F
RCFIELD4 DS F
END
Runtime log:
/start-assembh % BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED % ASS6010 <ver> OF BS2000 ASSEMBH READY //compile source=*library-element(macexmp.lib,possig), - // compiler-action=module-generation(module-format=llm), - // module-library=macexmp.lib, - // listing=parameters(output=*library-element(macexmp.lib,possig)), - // test-support=*aid % ASS6011 ASSEMBLY TIME: 509 MSEC % ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES % ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS % ASS6006 LISTING GENERATOR TIME: 84 MSEC //end % ASS6012 END OF ASSEMBH /load-executable-program library=macexmp.lib,element-or-symbol=possig, - / test-options=*aid % BLS0523 ELEMENT 'POSSIG', VERSION '@' FROM LIBRARY ':2OSG:$QM212.MACEXMP.LIB' IN PROCESS % BLS0524 LLM 'POSSIG', VERSION ' ' OF '<date> <time>' LOADED /%in dth1;%r STOPPED AT LABEL: DTH1 , SRC_REF: 158, SOURCE: POSSIG , PROC: POSSIG /%d %@(rcfield1) -> %x *** TID: 005000D8 *** TSN: 2QSE ********************************************* CURRENT PC: 000000A6 CSECT: POSSIG ************************************** V'000000FC' = POSSIG + #'000000FC' —————————————————————————————————— (7) 000000FC (000000FC) 00000000 .... /%d %@(rcfield2) -> %x V'00000100' = POSSIG + #'00000100' —————————————————————————————————— (8) 00000100 (00000100) 00000000 .... /%d %@(quitt) -> %x V'000000F8' = POSSIG + #'000000F8' —————————————————————————————————— (9) 000000F8 (000000F8) 00000004 .... /%d %@(rcfield3) -> %x, %@(rcfield4) -> %x ———————————————————————————— (10) V'00000104' = POSSIG + #'00000104' 00000104 (00000104) 04000000 .... V'00000108' = POSSIG + #'00000108' 00000108 (00000108) 04000000 .... /%r
(1) | The event item EVENT is defined. KKEV is the address of the ID. |
(2) | The POSSIG macro is used to post a signal to the event item. A contingency process as acknowledgment is not specified. As no other participant requests the signal by means of SOLSIG, the signal remains in the POSSIG event queue until the waiting time has expired (here 600 seconds, default value). |
(3) | The COANF contingency process is defined by the ID address KKCO (see the ENACO macro). |
(4) | A second signal is posted to the event item. The contingency process (ID address KKCO) is to be started after 60 seconds unless a previous SOLSIG macro has already initiated the start. After this POSSIG call the program idles in a wait loop. |
(5) | The basic process stores register 2 (event information code) under ACKNO, closes the contingency definition (DISCO) and disables eventing (DISEI). |
(6) | The COANF contingency process is started. The event information code in register 2 specifies that no SOLSIG macro arrived. By means of the CONTXT macro it is transferred from register 2 of the contingency process to register 2 of the basic process (see the CONTXT macro). After this the loop variable is changed to open the idle loop and the contingency process is terminated by means of the RETCO macro. |
(7) | Return switch after the first POSSIG macro (see (2)): posting of signal was successful. |
(8) | Return switch after the second POSSIG macro (see (4)): posting of signal was successful. |
(9) | Event information code of contingency process: the expected event did not occur within the waiting time. Neither contingency message nor post code exists. |
(10) | Return switch after the DISCO and DISEI macros: the contingency definition and the event item were disabled. |
For further examples, see the sections “Eventing” ("Eventing") and “Contingencyprocesses” ("Contingency processes")