General
Application area: | Eventing; see "Eventing" |
Macro type: | Type S, MF format 1: standard/L/E form; see "S-type macros" |
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 issue a “SOLicit SIGnal request” for an event item. The event item must previously have been assigned to the calling task (by ENAEI). The task can wait until an event occurs (synchronous operation) or, if the task is to be continued, until a contingency process is initiated as a result of the event (asynchronous operation).
In either case the task is continued (or the contingency process is initiated) once a specified period of time has elapsed - even if the event does not occur.
The contingency process must previously have been defined (by ENACO).
Note
If a program (package) has defined a contingency process written in SPL, register R12 must contain the address of the SPL program manager for all ENACO, SOLSIG and POSSIG calls.
Macro format and description of operands
SOLSIG |
{ {EINAME=name / EINAMAD={addr / (r)}}[,EINAMLN=length]} [,SCOPE={LOCAL / GROUP / USER_GROUP / GLOBAL]} / EIID={addr / (r)} } { ,COND=UNCOND[, {RPOSTAD={addr / (r)} / RPOSTR=r}][,RPOSTL={1 / 2}][,LIFETIM={sec / (r)}] / ,COND=IMMED[, {RPOSTAD={addr / (r)} / RPOSTR=r }] ,RPOSTL={1 / 2} / ,COID={addr / (r)}[,COMAD= {addr / (r)}][,COND=PERM][,LIFETIM={sec / (r) }] [,PARMOD=24 / 31] [,MF=L / (E,..)] |
EINAME=name
Specifies the name of the event item to which the requested event is signaled. The event item must already have been defined (ENAEI). The name of the event item is unique only in conjunction with SCOPE.
EINAMAD=
Specifies the name of the event item. This entry is unique only in conjunction with SCOPE.
addr
Symbolic address of the field containing the name.
(r)
Register containing the address of the field.
EINAMLN=length
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 (group of participants) of the event item.
LOCAL
Default setting: 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. This ID is supplied to the user by the ENAEI macro. If the ID is used instead of the name of the event item, processing is speeded up. The ID is unique.
addr
Symbolic address of a 4-byte field containing the 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).
Operands for synchronous operation
COND=
Specifies whether or not the caller is willing to wait for the event to occur.
UNCOND
Denotes that the caller is willing to wait for the event to occur. The waiting time can be restricted with the aid of the LIFETIM operand.
IMMED
Denotes that the caller is not willing to wait for the event to occur. The program must be continued even if the event was not yet signaled to the event item by a POSSIG macro. More information is supplied by the secondary indicator X'20' in register 15 (see “Return information and error flags” below).
RPOSTAD=
Specifies a field to which a post code is to be transferred. The post code may be 4 or 8 bytes long. The RPOSTL operand determines whether only the first word or both words of the post code are to be placed in the field.
The RPOSTR operand has the same function as this operand and, if it is used, processing is speeded up.
The address value 0 is not allowed.
addr
Symbolic address of the field to receive the post code. Field length = 4 or 8 bytes.
(r)
Register containing the address value “addr”.
RPOSTR=r
Indicates a register where the post code is to be entered directly. A two-word post code is entered in this register and the one following it (in number) if RPOSTL=2 is specified.
r
Register to receive the post code.
RPOSTL=
Gives the length in words of the post code to be received. If the 24-bit interface (PARMOD=24) is used, only RPOSTL=1 is permitted.
1
Default setting: only one word (the first word) of the post code is to be transferred.
2
The complete post code (2 words) is to be transferred.
LIFETIM=
Time for which the task is to wait for an event to occur. The return information indicates whether the request was satisfied or the waiting time elapsed. The operand is ignored if COND=IMMED is specified.
sec
Time in seconds. 1 <= sec <= 43200
The processing accuracy is +10 seconds.
Default value: 600 sec.
(r)
Register containing the specification in seconds.
Operands for asynchronous operation
COID=
Specifies the ID of the contingency process. The ID is supplied to the user by the ENACO macro call.
addr
Symbolic address of a 4-byte field containing the ID.
(r)
Register containing the address.
COMAD=
Specifies a contingency message. A contingency message issued here replaces any which might have been issued when the contingency was defined (by ENACO).
addr
Symbolic address of a word containing a contingency message.
(r)
Register containing the address.
COND=PERM
Permanent asynchronous SOLSIG:
If the signal requested by SOLSIG arrives (via POSSIG) within the waiting time (LIFETIM), another SOLSIG macro is issued. The waiting time for this second macro is 600 seconds. If no signal arrives during this waiting time, no further SOLSIG macro is issued.
LIFETIM=
Time during which the event should occur. The event information code notifies the contingency task as to whether or not the request was honored within the specified period of time.
sec
Time in seconds. 1 <= sec <= 43200
The processing accuracy is +10 seconds.
Default value: 600 sec
(r)
Register containing the time specification in seconds.
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 macro is transferred in register R15.
X'bb' | X'aa' | Meaning |
X'00' | X'00' | Function executed:
|
X'30' | X'00' | Function executed: post code information was provided (POSSIG) but SOLSIG did |
X'34' | X'00' | Function executed: no post code information was provided (POSSIG) although |
X'38' | X'00' | Function executed: post code exceeds specified receiving field in length. The 2nd |
X'3C' | X'00' | Function executed: post code is shorter than the receiving field. It is entered |
X'0C' | X'04' | No action: the event item established by the system has not been assigned to the |
X'10' | X'04' | No action: invalid operands were specified |
X'14' | X'04' | No action: invalid name or ID. No event item with the specified identification exists |
X'18' | X'04' | No action: maximum number (400) of contingency processes allowed per basic |
X'20' | X'04' | No action: the event did not occur. |
X'24' | X'04' | No action: invalid contingency process ID. No contingency process with this ID |
X'28' | X'04' | No action: the event item was deleted before the event occurred |
Example: synchronous operation
SOLSIG START
PRINT NOGEN
SOLSIG AMODE ANY
GPARMOD 31
1 *,MACRO: GPARMOD, VERSION: VER121
BALR 3,0
USING *,3
ENAEI EINAME=EVENT,SCOPE=GLOBAL,EIIDRET=KK ————————————————— (1)
GDATE TOD=TIME1
SOLSIG EIID=KK,COND=UNCOND ————————————————————————————————— (2)
*** WAITING FOR SIGNAL ***
GDATE TOD=TIME2
ST 15,RCFIELD1
GDATE TOD=TIME3
SOLSIG EIID=KK,COND=UNCOND,LIFETIM=70 —————————————————————— (3)
*** WAITING FOR SIGNAL ***
GDATE TOD=TIME4
ST 15,RCFIELD2
GDATE TOD=TIME5
SOLSIG EIID=KK,COND=IMMED —————————————————————————————————— (4)
GDATE TOD=TIME6
ST 15,RCFIELD3
CHKEI EIID=KK —————————————————————————————————————————————— (5)
ST 15,RCFIELD4
DISEI EIID=KK
DTH1 TERM
**** DEFINITIONS *****
KK DS F
TIME1 DS CL8
TIME2 DS CL8
TIME3 DS CL8
TIME4 DS CL8
TIME5 DS CL8
TIME6 DS CL8
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,solsig), - // compiler-action=module-generation(module-format=llm), - // module-library=macexmp.lib, - // listing=parameters(output=*library-element(macexmp.lib,solsig)), - // test-support=*aid % ASS6011 ASSEMBLY TIME: 453 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=solsig, - / test-options=*aid % BLS0523 ELEMENT 'SOLSIG', VERSION '@' FROM LIBRARY ':2OSG:$QM212.MACEXMP.LIB' IN PROCESS % BLS0524 LLM 'SOLSIG', VERSION ' ' OF '<date> <time>' LOADED /%in dth1;%r STOPPED AT LABEL: DTH1 , SRC_REF: 287, SOURCE: SOLSIG , PROC: SOLSIG /%d %@(time1) -> %cl8,%@(time2) -> %cl8 ——————————————————————————————— (6) *** TID: 005000D8 *** TSN: 2QSE ********************************************* ** CURRENT PC: 00000136 CSECT: SOLSIG ************************************** ** V'00000158' = SOLSIG + #'00000158' 00000158 (00000158) 13:14:15 V'00000160' = SOLSIG + #'00000160' 00000160 (00000160) 13:24:53 /%d %@(rcfield1) -> %x ———————————————————————————————————————————————— (7) V'00000188' = SOLSIG + #'00000188' 00000188 (00000188) 20000004 .... /%d %@(time3) -> %cl8,%@(time4) -> %cl8 ——————————————————————————————— (8) V'00000168' = SOLSIG + #'00000168' 00000168 (00000168) 13:24:53 V'00000170' = SOLSIG + #'00000170' 00000170 (00000170) 13:26:02 /%d %@(rcfield2) -> %x ———————————————————————————————————————————————— (9) V'0000018C' = SOLSIG + #'0000018C' 0000018C (0000018C) 20000004 .... /%d %@(time5) -> %cl8,%@(time6) -> %cl8 ——————————————————————————————— (10) V'00000178' = SOLSIG + #'00000178' 00000178 (00000178) 13:26:02 V'00000180' = SOLSIG + #'00000180' 00000180 (00000180) 13:26:02
/%d %@(rcfield3) -> %x ———————————————————————————————————————————————— (11) V'00000190' = SOLSIG + #'00000190' 00000190 (00000190) 20000004 .... /%d %@(rcfield4) -> %x ———————————————————————————————————————————————— (12) V'00000194' = SOLSIG + #'00000194' 00000194 (00000194) 30000000 .... /%r
(1) | The event item EVENT is defined. KK is the address for the ID. |
(2) | The task solicits a signal from the event item. The caller is willing to wait for the arrival of the signal until the end of the default waiting time (10 minutes). |
(3) | A second signal is requested. In this case, the waiting time is only 70 seconds. |
(4) | A third signal is requested. The task will not wait for it. As no signal has been posted in the POSSIG event queue, the task is continued immediately. |
(5) | The queues of the event item EVENT are checked. They are empty because the waiting times of all SOLSIG macros have expired. Then the definition of the event item is disabled. |
(6) | Time of day before and after the SOLSIG macro with default waiting time: the waiting time was 10 minutes and 38 seconds. |
(7) | Return code X'20000004' after the first SOLSIG call: the event did not take place. |
(8) | Time of day before and after the SOLSIG call with 70 seconds waiting time: the waiting time was 69 seconds. |
(9) | Return code X'20000004' after the second SOLSIG call: the event did not take place. |
(10) | Time of day before and after the SOLSIG macro without waiting time: no waiting time. |
(11) | Return code X'20000004' after the third SOLSIG call: the event did not take place. |
(12) | Result of the check of the receive queues by means of CHKEI: there are no requests in the receive queues. |
For examples, see the sections “Eventing” ("Eventing") and “Contingency processes” ("Contingency processes").