CONTROL=STSN

Setti ng of I BSOA L

or OBSOAC Field Purpose

SET Reset the sequence number and also send it to the logical unit.

TESTSET Reset the sequence number, send it to the logical unit, and obtain reply.

INVALID Obtain the sequence number from the logical unit.

IGNORE Send the sequence number to the logical unit, but do not reset the sequence number.

Figure 11. The Major SESSIONC Options

139

When the application program and the terminal discover that their inbound or outbound sequence numbers are different, the application program uses STSN indicators to communicate with the terminal. The purpose is to establish the correct sequence number while traffic flow is suspended. STSN indicators are used in conjunction with SDT and clear indicators as described in VT AM 111acro Language Guide.

There are four STSN indicators that the application program can send to the terminal: SET, TESTSET, INVALID, and IGNORE. The effects of these STSN indicators are discussed below under the IBSQAC and OBSQAC operand descriptions.

A SESSIONC macro instruction can be used to send STSN indicators that apply to either the inbound or. the outbound sequence numbers, or that apply to both independently.

When SDT, clear, and STSN indicators are sent to the terminal, a normal or exception FME response is returned as part of the SESSIONC operation. T.,hat is, the indicator is sent as though POST= RESP and RESPOND=(NEX,FME,NRRN) had been specified on a SEND macro instruction. If an exception response is returned, the SSENSEI, SSENSMI, and USENSEI fields are set as they would be for any other type of response.

Name Operation Operands

[symbol] SESSIONC RPL=rpl address

[ , rpl field name=new value] ...

RPL=rpl address

Indicates the location of the RPL that describes the SESSIONC operation.

,

rpl field name=new value

Indicates an RPL field to be modified and the new value that is to be contained or represented within it. If you wish to avoid the possibility of program reassembly following future releases of VTAM, set the RPL field with MODCB macro instructions rather than with the SESSIONC macro instruction.

Format: For rpl field name code the keyword of the RPL macro instruction operand that corresponds to the RPL field being modified. ARG can also be coded.

The new value can be any value that is valid for that operand in the RPL macro instruction, or it can indicate a register. Register notation must be used if ARG is used. Although any RPL operand can be specified, the following apply to a SESSIONC macro instruction:

ACB=acb address

Indicates the ACB that identifies the application program and was used when the terminal was connected.

AFt<i=(regjster)

The SESSIONC macro instruction is always directed at one specific terminal. The ARG operand specifies the register containing the CID of that terminal. If the ARG field is not modified, the CID already in the RPL's ARG field is used.

ECB I EXIT=ecb or rpl exit-routine address

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASy) SESSIONC request is completed. A SESSIONC request is completed when the SESSIONC indicator has been sent to the terminal and a response to it has been returned and posted in the RPL (similar to a SEND request with POST=RESP). If EXIT is specified, the RPL exit-routine is scheduled. Otherwise, the ECB is posted and CHECK or WAIT must be used to determine when the posting occurs. See the RPL macro instruction for more information.

OPTCD=SYN I ASY

When SYN is set, control is returned to the application program when the SESSIONC request is completed (the request is completed when the indicator has been sent and a response has been returned). When ASY is set, control is returned as soon as VTAM has accepted the SESSIONC request; once the requested operation has been completed, the ECB is posted or the RPL exit-routine is scheduled as indicated by the ECB-EXIT field. See the RPL macro instruction for more information.

CONTROL=SDT I CLEAR ISTSN CONTROL=SDT

Sends a start-data-traffic indicator to the terminal. The effect of this indicator is to allow the flow of messages and responses to begin (or to resume, if a clear indicator has been issued to stop the flow). When SDT=SYSTEM is coded as part of the terminal's NIB, VT AM automatically sends a start-data-traffic indicator as part of the connection process. If SDT=APPL is coded instead, it is the application program's responsibility to send the indicator when data traffic is to begin.

CONTROL=CLEAR

Sends a clear indicator to the terminal. The effect of this indica tor is to stop the flow of messages and responses and to discard data that is still in the network.

All SEND, RECEIVE, RESETSR, and SESSIONC requests in progress are completed normally or with RTNCD=12 and FDBK2=12 (SYNAD entered). All subsequent SEND and RESETSR requests will be rejected with a RTNCD=20 and FDBK2=65 (LERAD entered). Before SESSIONC is completed, VT AM sets the inbound and outbound sequence numbers to

o.

CONTROL=STSN

Sends a set-and-test-sequence-number indicator to the terminal. The effect of the STSN indicator depends on its type (as specified in the IBSQAC and OBSQAC fields) and the sequence number sent with it (as specified in the IBSQV AL and OBSQVAL fields).

IBSQV A L=inbound sequence number

Indicates a value that is 1 less than the new value that VT AM is to begin assigning to inbound messages. The application program sets this field only if SET or TESTSET is also specified in the IBSQAC field. The IBSQVAL field may be modified by the STSN response.

OBSQV AL=outbound sequence number

Indicates a value that is 1 less than the new value that VTAM is to begin assigning to outbound messages. The application program sets this field only if SET or TESTSET is also specified in the OBSQAC field. The OBSQV AL field may be modified by the STSN response.

141

Example

Return of Status Information

IBSQAC=SET I TESTSET I INVALID I IGNORE OBSQAC=SET

I

TESTSET

I

INVALID

I

IGNORE

The IBSQAC (inbound sequence number action code) and the OBSQAC (outbound . sequence number action code) fields designate the type of STSN indicator sent to the terminal. The application program can set either or both of these fields. The effect of setting one is identical to the effect of setting the other, except that one applies to incoming messages and the other to outgoing messages. Figure 12 summarizes the STSN indicator types and the responses they can elicit from the terminal.

SET

Sets the inbound or outbound sequence number to the value specified in the IBSQV AL or OBSQV AL field. When SESSIONC is completed, the IBSQAC or OBSQAC field contains the terminal's response to the new value: TESTPOS (agree) or RESET (set the sequence number again).

TESTSET

Sets the inbound or outbound sequence number as does SET, but a wider range of responses to the new value are possible: TESTPOS (agree), TESTNEG (disagree), INVALID (don't know) or RESET (set the sequence number again).

INVALID

Is used to obtain the terminal's version of the appropriate sequence number.

Unlike SET and TESTSET , INVALID does not set the sequence number (INVALID is used when the application program has lost its version of the sequence number). The terminal can reply to this type of STSN indicator in three ways: TESTNEG (my version enclosed), INVALID (don't know either), or RESET (set the sequence number).

IGNORE

Is used to send a sequence number to the terminal without setting the sequence number. The terminal does not return any action code.

SESSCI SESSIONC RPL=RPLI ,CONTROL=STSN ,OBSQAC=TESTSET OBSQV AL=(3),IBSQAC=IGNORE

SESSC 1 sends an STSN indicator to a terminal and sets the VT AM-supplied outbound sequence number to the value contained in register 3. The terminal, noting that the type of STSN indicator is TESTSET, can indicate TESTPOS, TESTNEG, INVALID, or RESET with its response. The response information is available in RPLI when SESSClis completed. If OBSQAC is found by the application program to be set to TESTPOS or TESTNEG, the OBSQVAL field contains the terminal's version of the outbound sequence number.

After the SESSIONC operation is completed, the follOWing RPL fields are set:

The value 37 (decimal) is set in the REQ field, indicating a SESSIONC request.

The value originally set in the USERFLD field of the NIB is set in the USER field of the RPL.

TheIBSQAC and/or OBSQAC fields are set to TESTPOS, TESTNEG,INVALID, or RESET depending on the codes initially set in these fields when SESSIONC was issued. Figure 12 lists the codes that can be returned for each code initially set.

Value of the I BSOAC or OBSOAC field Possible I BSOAC or OBSOAC field

when SESSIONC issued setting when SESSIONC completed

SET Sequence number reset to value in TESTPOS Terminal agrees with value. Value IBSOVAL or OBSOVAL field. returned in IBSOVAL or OBSOVAL

field.

RESET Terminal requests another STSN indicator. No value returned.

TESTSET Sequence number reset to value in TESTPOS Terminal agrees with value. Value IBSOVAL or OBSOVAL field. returned in IBSOVAL or OBSOVAL

field.

TESTNEG Terminal disagrees with value.

Terminal's version returned in IBSOVAL or OBSOVAL field.

INVALID Terminal does not know the value.

No value returned.

RESET Terminal requests another STSN indicator. No value returned.

INVALID Application program does not know TESTNEG Terminal knows the value. Value the sequence number value. returned in IBSOVAL or OBSOVAL

field.

INVALID Terminal doesn't know the value either. No value returned.

RESET Terminal requests another STAN indicator. No value returned.

IGNORE Application program is sending a None Terminal receives the sequence sequence number (as set in the number value but returns no INSOVAL or OBSOVAL field) I BSOAC or OBSOAC code and no without resetting the number. IBSOVAL or OBSOVAL value.

Figure 12. Types of STSN Indicators and Their Possible Responses

The IBSQVAL and/or OBSQVAL fields contain a sequence number when the IBSQAC and/or OBSQAC field is set to TESTPOS or TESTNEG. See Figure 12.

If an exception response is returned, the SSENSEI field may contain a system sense code. The possible codes (PATH, CPM, STATE, FI, or RR) are described near the end of Appendix C.

If an exception response is returned, the SSENSMI field may contain a system sense modifier value. This value, combined with the system sense code contained in the SSENSEI field, describes the specific type of error that causes the exception condition to be raised. See Appendix C. This value is tested as a I-byte quantity.

If an exception response is returned, the USENSEI field may contain a user sense value. This value is tested as a 2-byte quantity.

The RTNCD and FDBK2 fields are set as indicated in Appendix C.

Registers 0 and 15 are also set as indicated in Appendix C.

143

~.tlLUGON

SETLOGON-Reset an ACB's Logon Status

There are three types of SETLOGON requests: QUIESCE, START, and STOP. The QUIESCE-START-STOP option code.in SETLOGON's RPL determines which type is used. None of these three versions has any effect unless the ACB was opened with

MACRF= LOGON set. .

The START version of SETLOGON causes any application program issuing INQUIRE (OPTCD=APPSTAT) to receive a return code indicating that your application program is accepting logon requests. The first SETLOGON (OPTCD=

START) issued after OPEN causes VTAM to begin scheduling the LOGON exit-routine for all automatic logon requests, for all new logon requests, and for any logon requests already queued. SETLOGON (OPTCD=START) reverses the effect of SETLOGON (OPTCD=STOP), but it does not reverse the effect of SETLOGON (OPTCD=QUlESCE).

The STOP version of SETLOGON does not close the logon request queue; any CLSDST-initiated logon requests from other application programs cause the LOGON exit-routine to be scheduled. However, any application program issuing INQUIRE (OPTCD=APPSTAT) for your ACB receives a return code indicating that logon requests should not be directed at the ACB.

The QUIESCE version of SET LOGON causes VT AM to prevent logon request queuing. There is no way to reopen the logon request queue short of closing the ACB and then reopening it. An application program might want to use this type of SET LOGON at the end of a day's work, prior to closing the ACB; this would give the application program a chance to handle its current load of logon requests without receiving new ones. Any application program issuing INQUIRE (OPTCD=

APPSTAT) for your ACB will receive a return code indicating that your application program is shutting down and cannot receive logon requests.

The STOP and QUIESCE versions of SETLOGON do not prevent the queuing of logon request that originates from logical units.

To summarize: the LOGON exit-routine to be scheduled.

SETLOGON cannot be used to permit LOGON exit list routine scheduling; only closing the ACB and reovening it with MACRF= LOGON will permit this.

LOGON exit-routine scheduling can be started by a subsequent SETLOGON (OPTCD=START)

LOGON exit-routine scheduling begins for all queued, new, and automatic logon requests. If a LOGON exit-routine is available, each logon request causes it to be scheduled. If a routine is not available, the request is queued awaiting an OPNDST (OPTCD=ANY) macro instruction.

SET LOGON

SET LOGON

Name

RPL=RPLl, OPTCD=STOP

RPL=RPLl, OPTCD=QUIESCE

Operation Operands

SETLO(JON

Does not stop the scheduling of the LOGON exit-routine, but causes applica-tion programs issuing INQUIRE (OPTCD=APPSTAT) to receive a return code indicating that logon requests should not be issued for your application program.

Logon request permanently closed; it can be reopened only by closing and reopen-ing the ACB. Serves to notify other application programs issuing INQUIRE that logon requests cannot be accepted.

[symbol] SETLOGON RPL=rpl address

[, rpl field name=new value] ...

RPL=rpl address

Indicates the location of the RPL that in turn indicates the ACB whose logon status is to be changed.

rpl field name=new value

Indicates an RPL field to be modified, and the new value that is to be contained or represented within it. If you wjsh to avoid the possibility of program reassembly following future releases of VT AM, set the RPL field with MODCB macro instructions rather than with the SETLOGON macro instruction.

Format: For rpl field name code the keyword of the RPL macro instruction operand that corresponds to the RPL field being modified. The new value can be any value that is valid for that operand in the RPL macro instruction, or it can indicate a register.

Although any RPL operand can be specified, the following operands apply to a SET LOGON macro instruction:

ACB=acb address

Indicates the ACB that identifies the application program whose logon queuing status is being changed.

ECB

I

EXIT=ecb or rpl exit-routine address

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASy) SETLOGON macro instruction is completed. The macro instruction is completed immediately, subject to delays due to possible storage shortages. If EXIT is specified, ·the RPL exit-routine is scheduled. Otherwise, the ECB is posted, and CHECK or WAIT must be used to determine when posting occurs. See the RPL macro instruction for more information.

OPTCQ=SYN

I

ASY

When SYN is set, control is returned to the application program immediately, subject to possible delays due to storage shortages. When ASY is set, control is immediately returned to the application program, regardless of possible delays in 145

SETLOGON

Example

the completion of the macro instruction When the macro instruction is completed, the ECB is posted or the RPL exit-routine is scheduled, as indicated by the ECB-EXIT field.

OPTCD=QUIESCE

I

START

I

STOP

When QUIESCE is set, no more logon requests can be queued for your application program. When START is used, the scheduling of the LOGON exit-routine begins for all new, queued, and automatic logon requests. When STOP is used, users of INQUIRE (OPTCD=APPSTAT) receive a return code indicating that logon requests should not be directed at your application program. If logon requests are directed at your application program nonetheless, VT AM will accept them and queue them for an eventual OPNDST.

OPEN ACBl

BEGIN SETLOGON RPL=RPLl,ACB=ACBl,OPTCD=START

TOOMANY SETLOGON RPL=RPLl,ACB=ACBl,OPTCD=STOP

RESUME SET LOGON RPL=RPLl,ACB=ACBl,OPTCD=START

NOMORE SETLOGON RPL=RPLl,ACB=ACBl,OPTCD=QUIESCE

ACBl ACB

APPLNAME DC DC

APPLID=APPLNAME,MACRF=LOGON 'OS'

CL5'STOCK'

Before BEGIN is executed, the application program's LOGON exit-routine cannot be scheduled. Once BEGIN has completed however, STOCK's LOGON exit-routine is scheduled as each logon request occurs. (If the installation has defined a number of automatic logon requests, they will each cause the LOGON exit to be scheduled in turn.)

TOOMANY causes VT AM to flag the application program as temporarily unwilling to accept logon requests. It does not prevent logon requests from being queued for STOCK. If an application program that wants to direct a logon request at ACBl first issues INQUIRE (OPTCD=APPSTAT), it will receive a return code indicating that logon requests should not be issued for STOCK. The IBM-supplied network solicitor program always issues this type of INQUIRE and honors the flag set by TOOMANY.

RESUME reverses the effect of NOMORE; application programs issuing INQUIRE (OPTCD=APPSTAT) will receive a return code indicating that logon requests are being accepted (the same return code that results if INQUIRE is issued after BEGIN but before TOO MANY).

NOMORE closes the logon requests queue. An INQUIRE issued by another application program would indicate this, and any attempt to direct a logon request to STOCK would fail.

Return of Status Information

SETLOGON

After SETLOGON processing is finished the following RPL fields are set:

If OPTCD=QUIESCE, the number of logon requests queued for the ACB is set in the RECLEN field. This quantity can be examined with the SHOWCB macro instruction (a four-byte work area is required) or the TESTCB macro instruction.

The value 21 (decimal) is set in the REQ field, indicating a SETLOGON request.

The RTNCD and FDBK2 fields are set as indicated in Appendix C.

Registers 0 and 15 are also set as indicated in Appendix C.

147

SHOWCB

SHOWCB--Extract the Contents of Control Block Fields

SHOWCB extracts the contents of one or more ACB, EXLST, RPL, or NIB fields and places them into an area designated by the application program. The SHOWCB user specifies the address of a control block and the names of the fields whose contents are to be extracted. The field names are the same as the keywords of the ACB, EXLST, RPL, and NIB macro instructions. Any keyword of these macro instructions can be used as a field name in the SHOWCB macro instruction. See Appendix E for a list and explanation of the valid formats in which the SHOWCB operands can be specified.

Control block fields that can be operated on by SHOWCB are not limited, however, to fields that can be set by the application programmer in the ACB, EXLST, RPL, and NIB macros. Several additional fields whose contents are set only by VT AM

Control block fields that can be operated on by SHOWCB are not limited, however, to fields that can be set by the application programmer in the ACB, EXLST, RPL, and NIB macros. Several additional fields whose contents are set only by VT AM

Dans le document VTAM Macro Language Reference (Page 147-172)