The bridge facility is an emulated 3270 terminal. It is a virtual terminal, created by DFHL3270 when it receives a single transaction mode request, or a session mode request to allocate a bridge facility.
You do not provide a TERMINAL resource definition for the bridge facility, but you can control the terminal properties used by providing a 3270 TERMINAL resource definition to be used as a template. This TERMINAL definition, is known as the facilitylike.
The facilitylike value is the name of a real terminal resource definition that is used as a template for some of the properties of the bridge facility.
The name of the facilitylike definition to be used can be passed to CICS® in one of three ways (the first non-blank value found is used):
.
Once the bridge facility has been defined, its facilitylike template cannot be changed. Therefore, if the bridge facility is reused in session mode, CICS ignores the facilitylike value passed in subsequent calls.
See the CICS Resource Definition Guide for information about the PROFILE resource definition.
When CICS creates a bridge facility, it creates both an eight-byte token to identify it (the facilitytoken) and a four-character terminal identifier, which is used as both TERMID and NETNAME. The facilitytoken is returned on the Link3270 allocate call and must be supplied by you on all subsequent session mode calls ( See Using Link3270 session mode).
For bridge facilities created by the Link3270 bridge, the token and name are unique across the CICSplex, and the TERMID and NETNAME are of the form AAA}. Naming occurs in the routing region, at the time of processing an "allocate" command in session mode, or the internal allocate step in single-transaction mode. See Using the Link3270 bridge for information about session and single-transaction modes.
Link3270 bridge facility name space allocation information is recorded in a shared file, DFHBRNSF, to ensure uniqueness of the names. The router regions that share file DFHBRNSF and their associated AOR's form the bridge CICSplex. Multi-bridge CICSplexes can be set up within a larger CICSplex , each router region within a bridge CICSplex sharing the same DFHBRNSF file. The AOR regions of a bridge CICSplex can only be associated with router regions on one bridge CICSplex.
To improve performance, the Link3270 bridge name space is split into allocation ranges, so that a 'chunk' of names is allocated to each router region, and the DFHBRNSF file is only accessed when a name space range is allocated or released. Names within the allocated chunks can be reused when keeptimes expire, and chunks may also be reused in other regions, so you may see the same names appearing in different regions, but they are only active in one region at any given time.
Message DFHBR0505 is issued when 90% of the DFHBRNSF names have been allocated and is issued for each percentage point increase in the names being allocated. Message DFHBR0506 is issued for each percentage point reduction in names allocated until below 90%. When no more names are available, message DFHBR0507 is issued, and client application new allocation (or one shot) requests receive a return code of BRIHRC_NO_FREE_NAME.
The bridge facility name space allocation file (DFHBRNSF) can be a local user data table, a local VSAM file, a coupling facility data table (CFDT), a remote VSAM file or a VSAM RLS file.
If only one router region is used a user maintained data table or local VSAM version of DFHBRNSF is recommended.
If multi-router regions are used, the DFHBRNSF file can be defined as a local VSAM file in a remote file owning region (FOR) and as a remote VSAM file in the router regions; as a VSAM RLS in all the router regions, or as a coupling facility data table in all the router regions.
If the user maintained data table version of DFHBRNSF is used, the VSAM data set specified in the CICS file definition must be empty; no records should be loaded from the file to the data table. The data table should not be closed when the router region is running, because all bridge facility name space data will be lost and the next request to allocate or release a range of bridge facilities will fail. For this reason, a user maintained data table is not recommended for a production environment.
For VSAM files and data tables you will need to use IDCAMS to create file DFHBRNSF. Figure 12 shows a some sample IDCAMS statements that you can modify to create the DFHBRNSF file. The cluster name and volume values should be changed to comply with your own standards.
//DEFDS JOB accounting info,name,MSGCLASS=A
//TDINTRA EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
DEFINE CLUSTER(NAME(CICSTS22.CICS.DFHBRNSF)-
INDEXED-
TRK(1 1)-
RECORDSIZE(384 384)-
KEYS(13 20)-
FREESPACE(0 50)-
SHAREOPTIONS(2 3)-
LOG(NONE)-
VOLUME(DISK01)-
CISZ(512)) -
DATA (NAME(CICSTS22.CICS.DFHBRNSF.DATA)-
CISZ(512)) -
INDEX (NAME(CICSTS22.CICS.DFHBRNSF.INDEX)-
CISZ(512))
/*
//
See the CICS System Definition Guide for guidance on creating coupling facility data tables.
File DFHBRNSF contains two control records plus 1 record for each router region that accesses the file. The maximum number of records that can be written to DFHBRNSF is 731 (this includes the 2 control records).
You need to define file DFHBRNSF to CICS in the Link3270 router regions. Resource definitions have been provided for all versions of the file. You should include the appropriate group in your startup grouplist, or copy chosen definitions into a group in the grouplist. You will need to edit the definitions to match your IDCAMS statements. Change the DSN field to match the cluster name used with IDCAMS to create the file, unless the CFDT version of the file is to be used. If the CFDT definition is being used, change the CFDTPOOL value to the name of the pool containing the table defined by the file definition. The table below shows the groups provided that contain the DFHBRNSF definitions.
Group | Type |
---|---|
DFHBRVR | VSAM RLS |
DFHBRVSL | Local VSM, non-RLS |
DFHBRVSR | Remote VSAM, non-RLS |
DFHBRCF | Coupling facility data table |
DFHBRUT | User maintained data table |
During the normal termination of a CICS router region, new Link3270 requests are rejected and existing Link3270 facilities are released. When all facilities have been released, the DFHBRNSF name ranges associated with the router region are freed.
It is possible that the freeing of the DFHBRNSF name ranges will fail. For example, if file DFHBRNSF is remote, the shutdown transaction CESD breaks the connection to the file owning region before the name ranges have been freed. If this happens an error message will be issued. The name ranges are only freed when the CICS region is restarted and a Link3270 transaction has run in that region.
If the CICS termination is immediate, the Link3270 request is rejected with return code BRIH-CICS-TERMINATION, but the Link3270 facilities and DFHBRNSF name ranges associated with the facilities are not released. The name ranges are only freed when the CICS region is restarted and a Link3270 transaction has run in that region.
If the name or netname of the 3270 terminal is important to the logic of the 3270 application, you can supply a specific name in the BRIH-TERMINAL or BRIH-NETNAME parameter on the Link3270 call and also optionally request that the autoinstall user replaceable module (URM) is called when the bridge facility is allocated. The autoinstall URM is called if you specify the system initialization parameter AIBRIDGE=YES at CICS startup, or use SET AUTOINSTALL to activate this option at a later time.
The AUTOINSTALL URM can accept, reject or modify the supplied or generated terminal name and netname. See the CICS Customization Guide for information about the autoinstall URM.
The bridge facility can have a TCTUA (Terminal Control Table User Area), which can be accessed by EXEC CICS ADDRESS TCTUA in the normal way. The TCTUA is initialized to nulls when the bridge facility is created. A global user exit (GLUE) called XFAINTU is called when a bridge facility is created and discarded. XFAINTU is passed the address of the TCTUA, so you can use this exit to initialize the TCTUA. See the CICS Customization Guide for information about the XFAINTU global user exit.
The user transaction can retrieve information about its principal facility (the bridge facility) from the EIB or by using INQUIRE and ASSIGN commands, in exactly the same way that it does when running normally, where the principal facility is a real 3270. For example, the TERMID can be obtained from EIBTERMID or from an ASSIGN FACILITY, INQUIRE TASK FACILITY or INQUIRE NETNAME command, and the NETNAME can be obtained with ASSIGN NETNAME or INQUIRE TERMINAL.
You can use the INQUIRE BRFACILITY command to obtain information about any bridge facility, identified by its facilitytoken, but all other INQUIRE commands return only information about the bridge facility that is the principal facility of the transaction issuing the command. To other transactions, a transaction running in a bridged environment appears to be a non-terminal transaction, and an INQUIRE TERMID against a bridge facility TERMID issued by another transaction will result in TERMIDERR. INQUIRE NETNAME and INQUIRE TASK behave similarly.
Bridge facilities do not appear in response to INQUIRE TERMINAL browses.
All keywords of ASSIGN and INQUIRE are supported and return the values that have been set for the bridge facility from the FACILITYLIKE terminal definition, or that have been set during the execution of the transaction.
Some keywords return values fixed by CICS for the bridge environment. These are:
Keyword |
Returned value |
---|---|
ACQSTATUS |
ACQUIRED |
ACCESSMETHOD |
VTAM |
CORRELID |
blanks |
EXITTRACING |
NOTAPPLIC |
LINKSYSTEM |
blanks |
MODENAME |
blanks |
REMOTENAME |
blanks |
REMOTESYSTEM |
blanks |
REMOTESYSNET |
blanks |
SERVSTATUS |
INSERVICE |
TCAMCONTROL |
X'FF' |
TERMSTATUS |
ACQUIRED |
TTISTATUS |
YES |
ZCPTRACING |
NOZCPTRACE |
Keyword |
Returned value |
---|---|
FACILITY |
the bridge facility name |
FACILITYTYPE |
TERM or TASK |
STARTCODE |
S,SD,TO,TP |
The keywords listed below represent terminal attributes that can be set by the 3270 Query function at logon time for a real device:
ALTSCRNHT |
ALTSCRNWD |
APLKYBDST |
APLTEXTST |
BACKTRANSST |
COLORST |
EXTENDEDDSST |
GCHARS |
GCODES |
HILIGHTST |
MSRCONTROLST |
OUTLINEST |
PARTITIONSST |
PROGSYMBOLST |
SOSIST |
VALIDATIONST |
If the real FACILITYLIKE terminal is logged on when the bridge facility is created, the QUERY will have been performed and the values returned will apply to the bridge facility.
If the real FACILITYLIKE terminal is not logged on at the time that the bridge facility is created, the QUERY will not have been performed and the bridge facility will be created using values from the FACILITYLIKE resource definition.
The following table shows the effect of each of the SET TERMINAL/NETNAME keywords when issued by a user transaction for its bridge facility. Unless otherwise specified, the response is DFHRESP(NORMAL).
KEYWORD | EFFECT |
---|---|
ACQSTATUS | Ignored. |
ALTPRINTER | Value is SET, and is returned on INQUIRE, but is never used by CICS. |
ALTPRTCOPYST | Value is SET, and is returned on INQUIRE, but is never used by CICS. |
ATISTATUS | Works as for normal 3270. |
CANCEL | Ignored |
CREATESESS | Ignored. |
DISCREQST | Value is SET, and is returned on INQUIRE, but is never used by CICS. |
EXITTRACING | Ignored. |
FORCE | Ignored. |
MAPNAME | Works as for normal 3270. |
MAPSETNAME | Works as for normal 3270. |
NEXTTRANSID | Works as for normal 3270. |
OBFORMATST | Works as for normal 3270. |
PAGESTATUS | Ignored. |
PRINTER | Value is SET, and is returned on INQUIRE, but is never used by CICS. |
PRTCOPYST | Value is SET, and is returned on INQUIRE, but is never used by CICS. |
PURGE | Ignored. |
PURGETYPE | Ignored. |
RELREQST | Value is SET, and is returned on INQUIRE, but is never used by CICS. |
SERVSTATUS | Works as for normal 3270. |
TCAMCONTROL | Returns INVREQ, as for normal 3270. |
TERMPRIORITY | Value is SET, and is returned on INQUIRE, but is never used by CICS. |
TERMSTATUS | Ignored. |
TRACING | Value is SET, and is returned on INQUIRE, but is never used by CICS. |
TTISTATUS | Ignored. |
UCTRANST | Works as for normal 3270. |
ZCPTRACING | Ignored. |