UCF Front-End

The UCF front-end system executes in the host TP-monitor region/partition and communicates with terminals through host TP-monitor I/O facilities. The front-end communicates with the back-end system through the external request-unit service (ERUS) facility.
idms19
The UCF front-end system executes in the host TP-monitor region/partition and communicates with terminals through host TP-monitor I/O facilities. The front-end communicates with the back-end system through the external request-unit service (ERUS) facility.
UCF front-end systems can execute in dedicated or intermittent mode.
Dedicated mode
In dedicated mode, tasks execute as DC/UCF tasks and are invoked by the terminal operator in response to the ENTER NEXT TASK CODE prompt. While in dedicated mode, the terminal operator can execute DC/UCF tasks only; host TP-monitor tasks cannot be executed until dedicated mode is terminated.
To invoke dedicated mode, the terminal operator first enters the dedicated task code (or transaction id or verb, depending on the host TP monitor in use). This task code must be defined in the NTID parameter of the #UCFUFT macro (described in Front-end Table) and to the host TP monitor. Typically, only one dedicated task code exists (for example, DBDC). The terminal operator then signs on to the DC/UCF system.
To terminate dedicated mode and return to the host TP-monitor environment, the terminal operator enters the task code BYE or SUSPEND as follows:
  • BYE terminates dedicated mode and disconnects the front-end terminal from the UCF back-end. This action frees all resources that are held by the back-end for the terminal (for example, logical and physical terminal elements, signon element). The next time the terminal operator invokes dedicated mode, the DC/UCF signon must be performed.
  • SUSPEND terminates dedicated mode but does not disconnect the front-end terminal from the UCF back-end. All resources that are held by the back-end for the terminal are preserved. The terminal operator can invoke dedicated mode later in the session and can execute DC/UCF tasks without signing on again. When using a DC front-end with a DDS access method (CCI, TCP/IP, or VTAM), the SUSPEND task code is not supported and is treated as a BYE task code.
Intermittent mode
In intermittent mode, tasks execute as host TP-monitor tasks and are invoked by the terminal operator in response to the host TP monitor equivalent of the ENTER NEXT TASK CODE prompt; DC/UCF is transparent. DC/UCF tasks that are executed in intermittent mode must be defined to the host TP monitor and to the DC/UCF system with an intermittent task code. Any number of intermittent task codes can exist (for example, ADSG, DCMT, IDD, OLM).
When a DC/UCF task terminates on the back-end, the action that is taken depends on whether a back-end pseudo-converse exists and on the SUSPEND/DISCONNECT options in effect.
A back-end pseudo-conversation exists if the terminating task specifies a NEXT TASK CODE or an autotask is defined for the terminal. If a pseudo-conversation exists, the next task is invoked in the normal manner (similar to dedicated mode).
If the terminating task does not specify a NEXT TASK CODE and a terminal autotask is not defined, control is returned to the front-end TP-monitor. The ENTER NEXT TASK CODE prompt is never written when running in intermittent mode.
By default, the DC/UCF system issues the equivalent of a SUSPEND when ENTER NEXT TASK CODE would have been written. The front-end terminal is not disconnected from the UCF back-end; all resources that are held by the back-end for the terminal are preserved. The terminal operator can invoke dedicated mode or intermittent mode again later in the TP-monitor session and can execute DC/UCF tasks without signing on again.
Alternatively, the system can be directed to disconnect the terminal when the ENTER NEXT TASK CODE would have been written. If this option is desired, both of the following actions must be taken:
  • Compile and link the DC/UCF options module RHDCOPTF specifying #DEFOPTF OPT00020.
  • Compile and link the UCFCICS front-end module specifying #UCFCICS DISC=YES.
When this option is chosen, the DC/UCF system issues the equivalent of a BYE command when ENTER NEXT TASK CODE would have been written. The front-end terminal is disconnected from the UCF back-end. This action frees all resources that are held by the back-end for the terminal, for example, logical and physical terminal elements and signon element. The next time the terminal operator invokes a UCF task, a new DC/UCF signon will be performed.
The UCF batch, z/VM, and TSO front-ends can execute in dedicated mode only.
UCF Front-end Components
The UCF front-end system consists of the following items:
  • The UCF front-end common module (RHDCUCFC) contains code common to all TP monitors and is distributed in object form with the UCF system.
  • The appropriate TP-monitor interface module is distributed in macro form with the UCF system and must be assembled at your site.
  • The front-end module contains TP-monitor-dependent procedures. The front-end module is created by assembling a macro appropriate to the TP monitor in use.
  • The front-end table defines the characteristics of the front-end system terminals and supplies an identifier for the front-end system. The front-end table is created by assembling a series of macros.
Procedures for creating the front-end table, and for defining and using each front-end module follow.
2
2
Front-end Table
The front-end table defines global characteristics of a UCF front-end, including characteristics of the front-end terminals. One front-end table must be created for each UCF front-end to be used, except for the batch, z/VM, and TSO front-ends.
To create a UCF front-end table, assemble and link edit the following macros:
  • #UCFUFT supplies the global characteristics for the front-end system (for example, system identifier).
  • #UCFUTD identifies each terminal that is associated with the front-end system.
  • #UCFDEND ends the front-end table definition.
Front-end System and Terminal Identifiers
Each UCF front-end table contains an entry that identifies the front-end system and, optionally, an entry that identifies each terminal that is associated with the front-end system.
System Identifiers
Each front-end in a UCF system has an identifier that identifies to the DC/UCF system the TP monitor on which the front-end system task is executing. The system identifier (FESID) is used by the UCF back-end to determine whether a front-end is authorized to access the back-end. DCMT functions use the FESID to display and vary information that is associated with a front-end.
When a host TP monitor (front-end) signs on to a DC/UCF system (back-end) through UCF, the front-end system passes the system identifier to DC/UCF. The DC/UCF system attempts to locate the identifier in its system table before accepting the UCF signon. If the identifier passed with the signon is not in the system table, the signon is rejected. See UCF Back-End for a discussion of the UCF system table.
Usually, the system identifier is specified in the front-end table with the #UCFUFT macro. However, because the batch, z/VM, and TSO front-ends have built-in front-end tables, the system identifier for these interfaces must be specified in the TP-monitor-dependent macro.
Terminal Identifiers
Each terminal that is owned by a host TP monitor has a unique identifier. At runtime, the front-end task automatically passes the terminal identifier (FETID) to the DC/UCF system. The DC/UCF system uses the identifier with DCMT functions to display and vary information that is associated with that terminal.
The terminal identifier can be coded in the #UCFUTD macro for the terminal and/or in the PTERM statement for the terminal in the back-end system definition. At runtime, a terminal with no entry in the UCF front-end table (that is, one for which no identifier was coded in the #UCFUTD macro) will be assigned, by default, the characteristics of the prototype front-end terminal of the same type. If a prototype has not been defined for that terminal type, the terminal identifier must exist in the front-end table for a terminal to access UCF. Typically, you define prototypes for 3270- and TTY-type terminals; however, terminal identifiers
must
be supplied in the #UCFUTD macro for 3280-type terminals (printers).
Descriptions of the three macros that are used to create the UCF front-end table follow, with an example of a front-end table, and the front-end table JCL for z/OS, z/VSE, and z/VM.
#UCFUFT Macro
The #UCFUFT macro defines global front-end characteristics. One #UCFUFT macro is required for each front-end table. #UCFUFT must be the first macro in the source file and must be labeled.
Syntax
►►─── label #UCFUFT ──────────────────────────────────────────────────────────► ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ MODE = ─┬─ CONV ────┬─┘ └─ PCONV ◄──┘ ►─┬───────────────┬──────────────────────────────────────────────────────────► └─ ,ENV = IBM ◄─┘ ►─┬───────────────────────────────┬──────────────────────────────────────────► └─ ,NTID = dedicated-task-code ─┘ ►─┬───────────────────────────┬──────────────────────────────────────────────► └─ ,PTID = print-task-code ─┘ ►─┬─────────────────────────────────┬────────────────────────────────────────►◄ └─ ,SYSTEM = front-end-system-id ─┘
Parameters
  • MODE=CONV|PCONV
    (DC front-ends only) Specifies whether the front-end is to run in conversational or pseudo-conversational mode as follows:
    • CONV -- The front-end runs in conversational mode
    • PCONV (default) -- The front-end runs in pseudo-conversational mode
    The MODE specification can be overridden for selected terminals with the #UCFUTD macro (described on the following pages).
  • ENV=
    Defines the operating system environment. IBM is the default.
  • NTID=
    Specifies the one- through eight-character task code that is used to invoke the front-end in dedicated mode. dedicated-task-code must match the task code that is specified in the host TP-monitor system definition.
  • PTID
    (CICS and DC front-ends only) Specifies the one- through eight-character task code that is used to invoke the UCF Print Control Task. Print-task-code must match the task code that is specified in the CICS or DC system definition.
  • SYSTEM
    Specifies the one- through eight-character identifier for the front-end system (FESID). The front-end-system-id must be defined in the back-end system table and is typically one of the following identifiers: CICS, DC, or TSO
#UCFUTD Macro
The #UCFUTD macro defines terminal-specific characteristics. If no prototype terminals are defined, one #UCFUTD macro is required for each terminal that is associated with this front-end. If prototypes are defined, one #UCFUTD macro must be coded for each type of terminal (that is, 3270 and TTY) to be used with the UCF front-end. Typically, only one prototype TTY terminal and one prototype terminal for each 3270-type model present must be defined. #UCFUTD macros must be unlabeled.
Syntax
►►─── #UCFUTD ────────────────────────────────────────────────────────────────► ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ BUFSIZ = buffer-size ─┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ ,FORMFD = ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬───────────────────────┬──────────────────────────────────────────────────► └─ ,MODE = ─┬─ CONV ──┬─┘ └─ PCONV ─┘ ►─┬───────────────────────────────┬──────────────────────────────────────────► └─ ,MODEL = ─┬─ 2 ◄───────────┬─┘ └─ model-number ─┘ ►─┬───────────────────────────────┬──────────────────────────────────────────► └─ ,NCHARS = ─┬─ 80 ◄─────────┬─┘ └─ line-length ─┘ ►─┬───────────────────────────────┬──────────────────────────────────────────► └─ ,NLINES = ─┬─ 24 ◄─────────┬─┘ └─ page-length ─┘ ►─┬─────────────────────────────────┬────────────────────────────────────────► └─ ,PRTCLS = ─┬─ 1 ◄────────────┬─┘ └─ printer-class ─┘ ►─┬─────────────────────┬────────────────────────────────────────────────────► └─ ,SCS = ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬─────────────────────────────────┬────────────────────────────────────────► └─ ,TERM = front-end-terminal-id ─┘ ►─┬─────────────────────────┬────────────────────────────────────────────────►◄ └─ ,TYPE = ─┬─┬─ CRT ─┬─┬─┘ │ └─ TTY ─┘ │ ├─ T3277 ◄──┤ ├─ T3279 ───┤ └─ T3280 ───┘
Parameters
  • TERM=
    Specifies the unique identifier for the front-end terminal. Except when defining a 3280-type printer, this parameter is typically omitted and, therefore, defines a prototype terminal. front-end-terminal-id is a one- through eight-character alphanumeric value and must match the terminal identifier that is specified in the host TP-monitor system definition. This parameter is required if TYPE=T3280 is specified.
  • TYPE=
    Specifies the front-end terminal type as follows:
    • CRT|TTY -- The front-end terminal is a TTY-type terminal. TTY applies to all asynchronous ASCII terminals.
    • T3277 (default) -- The front-end terminal is a 3270-type terminal.
    • T3279 -- The front-end terminal is a 3279-type color terminal with extended color support.
    • T3280 -- The front-end terminal is a 3280-type terminal. If T3280 is specified, the TERM= parameter must also be specified.
  • MODE=CONV|PCONV
    (DC front-ends only) Specifies whether this terminal executes in conversational or pseudo-conversational mode as follows:
    • CONV -- The terminal executes in conversational mode.
    • PCONV -- The terminal executes in pseudo- conversational mode.
    The MODE= parameter defaults to the MODE specification in the #UCFUFT macro.
  • MODEL=
    (TYPE T3277 only) Specifies the 3270-type terminal model code. model-number is an integer in the range 1 through 5; the default is 2.
  • NCHARS=
    Specifies the terminal's line length. line-length is an integer in the range 1 through 32767; the default is 80 characters.
  • NLINES=
    Specifies the terminal's page length. page-length is an integer in the range 1 through 32767; the default is 24 lines. If TYPE=TTY is specified, a page length of 3 is recommended.
  • BUFSIZ=
    Specifies the size, in bytes, of the I/O buffer allocated to the terminal. buffer-size can be any positive integer in the range of 1-32300. The value that is specified must be greater than or equal to the size of the longest data stream to be transferred between the DC/UCF system and the UCF front-end system. Typically, the default value (equal to the product of 1.5 times the NCHARS value times the NLINES value plus 800) is used.
  • FORMFD=YES|NO
    (CICS and DC front-ends only) Specifies whether the printer front-end terminal has form feed capabilities as follows:
    • YES -- The terminal has form feed capabilities.
    • NO (default) -- The terminal does not have form feed capabilities.
  • PRTCLS=
    (CICS front-end only) Specifies a print class for WRITE TO PRINTER requests issued from the terminal. print-class is an integer in the range 1 through 64; the default is 1. This parameter is ignored if the terminal itself is a printer.
  • SCS IS NO|YES
    Specifies whether the printer is an SNA character string device, also known as a type 1 logical unit:
    • NO (default) indicates that the printer is not an SNA character string device.
    • YES indicates that the printer is an SNA character string device.
#UCFDEND Macro
The #UCFDEND macro specifies the end of the front-end table definition. One #UCFDEND macro must be coded for each front-end table. #UCFDEND must follow the last #UCFUTD macro and must be unlabeled.
Syntax
►►─── #UCFDEND ───────────────────────────────────────────────────────────────► ►──┬──────────────────┬──────────────────────────────────────────────────────►◄ └─ XA= ─┬─ YES ──┬─┘ └─ NO ◄──┘
Parameter
  • XA
    Determines whether the front-end table has the capability to reside above the 16-megabyte line. The default, NO, indicates that it does not have the capability. YES indicates that it has the capability.
Sample Front-end Table Definition
The following macro statements define a sample CICS front-end system, consisting of a prototype TTY-type terminal and five 3270-type terminals:
UCFFET #UCFUFT SYSTEM=CICS,NTID=DBDC #UCFUTD TYPE=TTY,NCHARS=80,NLINES=2 #UCFUTD TYPE=T3277,NCHARS=40,NLINES=12,MODEL=1 #UCFUTD TYPE=T3277,NCHARS=80,NLINES=24,MODEL=2 #UCFUTD TYPE=T3277,NCHARS=80,NLINES=32,MODEL=3 #UCFUTD TYPE=T3277,NCHARS=80,NLINES=43,MODEL=4 #UCFUTD TYPE=T3277,NCHARS=132,NLINES=27,MODEL=5 #UCFDEND
Front-end Table JCL
This section contains the JCL to create the UCF front-end table for z/OS and z/VSE operating systems. Alternatively, you can assemble a front-end table in the same input stream that creates a particular front-end module. For example, a z/OS UCF CICS front-end object module can be created by assembling a #UCFCICS macro, a #UCFUFT macro, appropriate #UCFUTD macros, and a #UCFDEND macro. A particular UCF CICS front-end load module can be created by using the JCL shown in the section CICS Front-end JCL, and then omitting the INCLUDE statement for ucffet.
To create a stand-alone front-end table under z/OS:
  1. Create a front-end table source module as follows:
    UCFFET #UCFUFT ucfuft-parameters #UCFUTD ucfudt-parameters . . . #UCFDEND END
  2. Save the source module in your custom source library.
  3. Assemble and link it into your custom load library by executing the z/OS Assemble and Link-Edit.
    Substitute the name of your front-end table source member and insert the following binder statement:
    • NAME ucffet(R)
      Name of the UCF front-end table load module.
To create a stand-alone front-end table under z/VSE:
  1. Assemble and catalog the table using the sample JCL in z/VSE Assemble JCL.
    Modify the JCL by substituting the following statements in place of the
    Assembler input statements
    :
    PUNCH 'CATALOG
    ucffet
    .OBJ REPLACE=YES' UCFFET #UCFUFT ucfuft-parameters #UCFUTD ucfudt-parameters . . . #UCFDEND END
    • ucffet
      Specifies the name for your UCF front-end table.
Batch Front-end
The UCF batch front-end enables the execution of DC/UCF tasks from a batch job.
To create the batch front-end module, assemble a #UCFBTCH macro and link edit the resulting object module with RHDCUCFC, CA IDMS, and IDMSOPTI (optional). The batch front-end supports dedicated mode only and requires no front-end table definition.
The IDMSOPTI module identifies the back-end system with which the front-end communicates. The module is created by assembling an IDMSOPTI macro. If you omit IDMSOPTI from the link edit of the front-end system, the execution JCL for the front-end must include a SYSCTL file that identifies the back-end system. For more information about IDMSOPTI, see Setting Up Interpartition Communication and the SVC.
#UCFBTCH Macro
Syntax for the #UCFBTCH macro follows. The macro must be labeled. The label provides the module entry point name.
Syntax
►►─── label #UCFBTCH ─────────────────────────────────────────────────────────► ►─┬───────────────────┬──────────────────────────────────────────────────────► └─ OS = ─┬─ OS ◄──┬─┘ └─ DOS ──┘ ►─┬───────────────────────┬──────────────────────────────────────────────────► └─ ,PRINT = ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ ,RETCD = ─┬─ YES ◄──┬─┘ └─ NO ────┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ ,INPLEN = ──┬─ 80 ◄─┬─┘ └─ nn ──┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ ,S015 = ─┬─ YES ◄──┬─┘ └─ NO ────┘ ►─┬───────────────────────────────────────┬──────────────────────────────────►◄ └─ ,SYSTEM = ─┬─ BATCH ◄──────────────┬─┘ └─ front-end-system-id ─┘
Parameters
  • OS=
    Specifies the operating system under which the batch front-end system executes. OS applies to all supported z/OS and z/VM operating systems. DOS applies to all supported z/VSE operating systems. The default is OS.
  • PRINT=YES|NO
    Specifies whether reports queued to DC printers can be printed using UCF batch printer support. NO, the default, indicates that the system creates the batch front-end load module; printer support is not generated. YES directs the system to create a UCF print support module. UCF print support is discussed later under Front-end Table.
  • RETCD=YES|NO
    If the CA IDMS system is shut down while a UCFBATCH job is running, the UCFBATCH job ends with a return code of 4 or 12. If RETCD=YES is specified, UCFBATCH jobs continue to run as they currently do and receive the non-zero return code. If RETCD=NO is specified, UCFBATCH jobs will not receive the return code of 4 or 12. The default is YES.
  • INPLEN=
    nn
    Specifies the number of columns that UCF processes as input on each record within the input file. Columns following the specified length are ignored.
    Default:
    80
    Note:
    If you use the default and the input file contains sequence numbers in columns 73 through 80, then you might receive syntax errors. To avoid the errors in this situation, specify INPLEN=72 instead of using the default.
  • S015=YES|NO
    Specifying S015=YES or defaulting to S015=YES will not change the Current behavior of the UCF Batch front-end. Coding S015=NO suppresses the following message:
    UCFBTCH S015 - NOTHING FOR PRINTER TO PRINT.
  • SYSTEM
    Specifies the 1 through 8-character front-end system identifier. front-end-system-id must match the identifier that is specified in the FESID parameter of the #FESTENT macro that is used to define the batch front-end in the UCF system table; see #FESTENT Macro for further information. The default of BATCH matches the FESID value for the batch front-end in the system table that is supplied with UCF.
Front-end Load Module Assembly JCL
This section contains the JCL to create the batch front-end load module for z/OS, z/VSE, and z/VM operating systems.
A default UCF batch interface module is provided during installation with the name RHDCUCFB. RHDCUCFB is created using macro input: #UCFBTCH SYSTEM=BATCH,OS=os
If you want to create your own UCF batch front-end load module, use the following procedure.
To create a z/OS front-end load module
  1. Create a UCFBTCH source module as follows:
    Ucfbtche #UCFBTCH #ucfbtch-parameters END
  2. Save the UCFBTCH source module in your custom source library.
  3. Assemble and link it into your custom load library by executing the z/OS Assemble and Link-Edit JCL.
    Substitute the name of your UCFBTCH source member and insert the following binder statements:
    INCLUDE CUSTLIB(
    idmsopti
    ) ENTRY
    ucfbtche
    SETOPT PARM(REUS=NONE,AMODE=31,RMODE=24) NAME ucfbtchi(R)
    • idmsopti
      (Optional) Specifies the name of your IDMSOPTI module.
    • ucfbtche
      Specifies the entry point name of your UCF Batch front-end load module.
      Note:
      Use UCFBTCHX or the name that is specified as the label on the assembler instruction that invokes the #UCFBTCH macro.
    • ucfbtchi
      Specifies the name of your UCF batch front-end load module.
To create a z/VSE batch front-end load module
  1. Assemble and catalog the module using the sample JCL in z/VSE Assemble JCL.
    Modify the JCL by substituting the following statements in place of the Assembler input statements:
    PUNCH 'CATALOG ucfbtcho.OBJ REPLACE=YES' ucfbtche #UCFBTCH #ucfbtch-parameters END
  2. Link the UCF batch phase using the sample JCL in z/VSE Link JCL.
    Modify the JCL by substituting the following statements in place of the Linkage editor control statements:
    PHASE uscfbtchi,* INCLUDE
    ucfbtcho
    INCLUDE
    idmsopti
    ENTRY ucfbtche
    • ucfbtcho
      Specifies the name of your UCF batch front-end object module.
z/VM batch front-end load module assembly
GLOBAL MACLIB idmslib FILEDEF TEXT DISK ucfbtch TEXT A ASSEMBLE #ucfbtch FILEDEF SYSLST PRINTER FILEDEF SYSLMOD DISK idmslib LOADLIB a2 (RECFM V LRECL 1024 BLKSIZE 1024 LKED linkctl
Linkage editor control statements (linkctl):
INCLUDE ucfbtch INCLUDE IDMSOPTI INCLUDE IDMS INCLUDE RHDCUCFC INCLUDE IDMSUTIO ENTRY IDMSENTR NAME ucfbtch(R)
idmslib
filename of the CA IDMS MACLIB library
idmslib LOADLIB a2
file ID of the CA IDMS LOADLIB library
linkctl
filename of the file containing the linkage editor control statements
ucfbtch
name of the batch front-end module
ucfbtche
label that is specified for #UCFBTCH
#ucfbtch
filename of the file containing the #UCFBTCH macro statement
Batch Front-end Execution
When executed, the batch front-end reads input from SYSIPT. Each statement is interpreted as terminal input and is passed to the DC/UCF system. The physical terminal name is used as the terminal identifier. Output from the DC/UCF task is returned to the front-end, which writes the output to SYSLST. The terminal disconnect occurs when the BYE task is invoked.
The batch front-end operates in dedicated mode only. You must provide a job card specifying a user ID and password to execute tasks with a security class other than zero. Alternatively, you can specify the SIGNON task code in the input:
SIGNON ABC ABCPASS DCMT DISPLAY ACTIVE TASKS DCMT DISPLAY ACTIVE PROGRAMS DCUF SHOW USERS ALL BYE
Batch Front-end Execution JCL
This section contains the JCL to execute the UCF batch front-end for z/OS, z/VSE, and z/VM operating systems.
z/OS batch front-end execution
// EXEC PGM=ucfbtch //STEPLIB DD DSN=
idms.custom.loadlib
,DISP=SHR // DD DSN=idms.cagjload,DISP=SHR //sysctl DD DSN=idms.sysctl,DISP=SHR //SYSUDUMP DD SYSOUT=A //SYSLST DD SYSOUT=A //SYSIDMS DD * SYSIDMS parameters, as required //SYSIPT DD * input statements /*
See Library and dataset References in z/OS JCL for variable information that is used in the example.
z/VSE batch front-end execution
// UPSI b
if specified in the IDMSOPTI module
// DLBL idmslib,'idms.library',2099/365,DA // EXTENT ,nnnnnn,,,ssss,1500 // LIBDEF *,SEARCH=(idmslib.sublib) // EXTENT SYSnnn,nnnnnn,,,ssss,54 // ASSGN SYSnnn,DISK,VOL=nnnnnn,SHR // DLBL SYSIDMS,'#SYSIPT',0,SD // EXEC ucfbtch
input statements
/*
You can define a SYSCTL file in the JCL to override IDMSOPTI specifications for the back-end system as follows:
// DLBL sysctl,'idms.sysctl',,SD // EXTENT sys008,nnnnnn // ASSGN sys008,DISK,VOL=nnnnnn,SHR
b
appropriate one- through eight-character UPSI bit switch, as specified in the IDMSOPTI module
idmslib
filename of the file containing CA IDMS modules
idmslib.sublib
name of the sublibrary within the library containing CA IDMS modules
idms.library
file-id that is associated with the file containing CA IDMS modules
idms.sysctl
file-id of the SYSCTL file
nnnnnn
volume serial number
ssss
starting track (CKD) or block (FBA) of disk extent
sysctl
filename of the SYSCTL file
sys008
logical unit assignment of the SYSCTL file
ucfbtch
phase name of the batch front-end module
z/VM batch front-end execution
FILEDEF SYSLST PRINTER FILEDEF SYSIPT DISK ucfbtch input a FILEDEF SYSIDMS DISK sysidms parms a (RECFM F LRECL lll BLKSIZE bbb GLOBAL LOADLIB idmslib OSRUN ucfbtch
You can define a SYSCTL file in the JCL to override IDMSOPTI specifications for the back-end system as follows:
FILEDEF sysctl DISK sysctl idms a
bbb
blocksize
idmslib
name of the CA IDMS LOADLIB library
lll
logical record length
sysctl
ddname of the SYSCTL file
sysctl idms a
file ID of the SYSCTL file
sysidms parms a
file ID of the SYSIDMS parameter file
ucfbtch
name of the batch front-end load module
ucfbtch input a
file ID of the file containing the UCF batch input statements
Setting Options for Batch UCF Program Execution
The SET OPTIONS input statement allows users to establish input options during batch UCF program execution. The words SET OPTIONS must start in column 1 and must be followed by a blank. Each of the following options is specified in a separate SET OPTIONS statement:
  • INPUT
    start-column
    THRU
    end-column
    specifies the start and end columns of the input column range. The batch front-end program treats data within the specified columns as input and ignores any other data on the line. The default range is 1 through 80. Typically, this parameter is used to limit the input column range to columns 1 through 72.
  • ECHO/NOECHO specifies whether subsequent input statements are written to SYSLST:
    • ECHO (default) specifies to write input statements to SYSLST.
    • NOECHO specifies not to write input statements to SYSLST.
SET OPTIONS statements are always echoed, regardless of the input options that have been established.
Example SET OPTIONS Statements
In the following example, SET OPTIONS statements limit input columns to 1 through 72 and request the program not to echo the user password:
//UCFBTCH EXEC PGM=UCFBTCH //STEPLIB DD DSN=idms.custom.loadlib,DISP=SHR // DD DSN=idms.cagjload,DISP=SHR //SYSCTL DD DSN=idms.sysctl,DISP=SHR //SYSLST DD SYSOUT=A //SYSUDUMP DD SYSOUT=A //SYSIPT DD * SET OPTIONS INPUT 1 THRU 72 SIGNON HARPO SET OPTIONS NOECHO SWORDFISH SET OPTIONS ECHO DCMT DISPLAY ACTIVE STORAGE 5 DCMT DISPLAY LINES BYE
CICS Front-End
The UCF CICS front-end enables DC/UCF tasks to be executed from a terminal that is connected to CICS.
A UCF CICS front-end program contains an options table and a small stub module that calls the main processing routines.
To create the CICS front-end module, assemble a #UCFCICS macro and link edit the resulting object module as shown in the following section.
UCF requires the presence of the IDMSINTC interface module in the CICS region/partition. For instructions on assembling and link editing IDMSINTC, see CICS Considerations.
#UCFCICS Macro
Syntax for the #UCFCICS macro follows. The macro must be labeled. The label provides the module entry point name.
Syntax
►►─── label #UCFCICS ─────────────────────────────────────────────────────────► ►─┬──────────────────────┬───────────────────────────────────────────────────► └─ COLOR = ─┬─ YES ──┬─┘ ├─ NO ◄──┤ └─ ONLY ─┘ ►─┬──────────────────────┬───────────────────────────────────────────────────► └─ DBCS = ──┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬──────────────────────┬───────────────────────────────────────────────────► └─,DEBUG = ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬─────────────────────────┬────────────────────────────────────────────────► └─DFLTSIZ = ──┬─ 24X80 ◄──┤ ├─ 32X80 ──┤ ├─ 43X80 ──┤ ├─ MOD2 ◄──┤ ├─ MOD3 ──┤ └─ MOD4 ──┘ ►─┬─────────────────────┬────────────────────────────────────────────────────► └─,DISC = ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬────────────────────────────────────┬─────────────────────────────────────► └─ ,ERRDCT = ─┬─ destination-name ─┬─┘ └─ CSMT ◄────────────┘ ►─┬────────────────────────────┬─────────────────────────────────────────────► └─,LASTOUT = ─┬─ TASKEND ───┬┘ └─ RESETKB ◄──┘ ►─┬────────────────────┬─────────────────────────────────────────────────────► └─ ,OS = ─┬─ OS ◄──┬─┘ └─ DOS ──┘ ►─┬────────────────────────────────┬─────────────────────────────────────────► └─,PRINT = ─┬─ print-option ───┬─┘ └─ OFF ◄───────────┘ ►─┬─────────────────────┬────────────────────────────────────────────────────► └─ ,RDW = ─┬─ YES ───┬┘ └─ NO ◄───┘ ►─┬──────────────────────────┬───────────────────────────────────────────────► └─ ,READBUF = ─┬─ YES ◄──┬─┘ └─ NO ────┘ ►─┬─────────────────────────┬────────────────────────────────────────────────► └─ ,RECVRTS = ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬────────────────────────────┬─────────────────────────────────────────────► └─,RESETKB = ─┬── TASKEND ──┬┘ └─ ASIS ◄─────┘ ►─┬─────────────────────────┬────────────────────────────────────────────────► └─,SUFFIX = ──── suffix ──┘ ►─┬─────────────────────────┬────────────────────────────────────────────────► └─ ,UCTRAN = ─┬─ TCT ──┬─┘ └─ NO ◄──┘ ►─┬─────────────────────────┬────────────────────────────────────────────────►◄ └─ ,USERCHK = ─┬─ YES ──┬─┘ └─ NO ◄──┘
Parameters
  • COLOR=YES|NO|ONLY
    Specifies whether the front-end is to check to see if the terminal is a 3279-type terminal with extended color support. If YES is specified, DC/UCF treats the terminal as a 3279 terminal if CICS reports positive settings for either the COLOR or EXTDS attributes. If ONLY is specified, DC/UCF treats the terminal as a 3279 terminal only if CICS reports a positive setting for the COLOR attribute. The default is NO.
  • DBCS=YES|NO
    Specifies whether the terminal supports double-byte characters. If YES is specified, terminals that support COLOR or extended data streams are assumed to also have Double Byte Character Support. COLOR=YES must be specified for DBCS=YES to take effect.
  • DEBUG=YES|NO
    Specifies whether EXEC CICS ENTER TRACEID commands are issued at various processing points during the execution of each UCF transaction. DEBUG=YES is only used for diagnostic purposes. The default is NO.
  • DFLTSIZ=24X80|32X80|43X80|MOD2|MOD3|MOD4
    Specifies the 3270 terminal model default display size to use when the terminal emulator alternate display size is not a standard 3270 model. To display properly, the terminal emulator default or primary display size should be aligned with this specification. The default is 24X80 or MOD2.
  • DISC=YES|NO
    Specifies what action the DC/UCF system is to take at the end of an intermittent mode pseudo-converse. DISC=YES specifies that all DC/UCF resources should be freed. DISC=NO specifies that the DC/UCF terminal should be put in a SUSPEND state. The default is NO.
    Note:
    If DISC=YES is specified, RHDCOPTF bit 20 must be set in the corresponding back-end DC system.
  • ERRDCT=
    Identifies the CICS transient data destination to be used as the target for error messages that are produced by IDMSINTC and IDMSTRUE. The default destination name is CSMT. Use another destination if you want to route CA IDMS error messages to another CICS destination. The DCT entry should be defined with a logical record length of at least 130 characters.
  • LASTOUT=TASKEND|RESETKB
    Specifies the action the UCFCICS front-end module takes when issuing WRITE commands. If LASTOUT=RESETKB, UCFCICS includes the LAST option on the EXEC CICS SEND command whenever it writes a data stream that includes the RESET keyboard indicator. If LASTOUT=TASKEND, UCFCICS does not specify the LAST option when writing data streams. CICS automatically transmits an "end-of-bracket" indicator at task end. RESETKB is the default.
  • OS=OS|DOS
    Specifies the operating system under which the CICS front-end system executes. OS applies to all supported z/OS versions of CICS. DOS applies to all supported z/VSE versions of CICS. The default is OS.
  • PRINT=print-option
    Specifies what print option the Assembler is to use while processing the COPY commands which copy in the DSECTs used in the UCF front-end module. Valid options are ON|GEN|NOGEN. See the documentation for your Assembler product for details. The default is OFF.
  • RDW=YES|NO
    Specifies whether UCFCICS should pass the RDW as part of the PDAT data when starting a front-end task in a distributed application as described in section 4.1. The default is NO.
  • READBUF=YES|NO
    Specifies whether the physical terminal can execute a READ BUFFER command; the default is YES. At bind time, the READBUF specification in the #UCFCICS macro overrides the READBUFFER/NOREADBUFFER specification that is established by the system generation PTERM statement for the physical terminal.
  • RECVRTS=YES|NO
    YES specifies that the CICS system is generated with RECOVERABLE AUX TEMP storage. This parameter may be needed for UCFPRINT to work properly on such systems. The default is NO.
  • RESETKB=TASKEND|ASIS
    Specifies whether the UCFCICS front-end module should suppress the RESET keyboard indicator when writing data streams. If YES is specified, the RESET indicator is removed from any data stream that is written to the terminal. This also prevents the LAST option from being specified on all EXEC CICS SEND commands. At task termination, an extra EXEC CICS SEND command is transmitted specifying zero length, RESET keyboard, and LAST.
    IF ASIS is specified, the RESET keyboard indicator is left as passed by the application code running in the DC/UCF back-end system. The LAST option is controlled by the LASTOUT parameter described previously. The default is ASIS.
  • SUFFIX=suffix
    SUFFIX is an obsolete parameter, but it is allowed for compatibility.
  • UCTRAN=TCT|NO
    Specifies whether to translate input data to uppercase before it is transferred to the DC/UCF system as follows:
    • TCT -- Translation of terminal input is determined by the presence or absence of the FEATURE=UCTRAN parameter in the TCT definition for the terminal.
    • NO (default) -- Terminal input is not translated to uppercase.
  • USERCHK=YES|NO
    Specifies whether UCFCICS is to check the CICS userid at the beginning of each task in a pseudo-converse. YES prevents an operator who has newly signed on to a terminal from being connected to another user's back-end UCF terminal session. This condition can occur if the first user's session was aborted (for example, by "killing" the session from a VTAM session manager) and UCFCICZ is not implemented to clean up the associated UCFCICS storage in the CICS region where the UCFCICS transaction runs.
    YES causes UCFCICS to check the CICS USERID at the beginning of each task in a pseudo-converse. If the userid does not match the userid that was saved from the previous task in that pseudo- converse, a new session is started instead of resuming the old one. The old session is automatically aborted. The new session continues normally.
    If CICS signon is not done, USERCHK=YES is not enforced.
    For example, consider the following scenario:
    • User A is on a CICS terminal, but is not signed on to CICS.
    • User A starts a UCF session and their CICS session is aborted while in a pseudo-converse.
    • User B comes into CICS and gets the same terminal. User B also is not signed on to CICS.
    • User B invokes UCF and picks up user A's session.
    In the scenario, if either user A or user B (or both) is signed on to CICS, the old session is aborted. The comparison of the new and saved userid is done after the call to the USRIDXIT, if that exit exists. The value set by the USRIDXIT is the one that is saved across a pseudo-converse, so the use of the exit with USERCKHK=YES should not cause a problem even if the exit modifies the user ID used to connect to the back-end DC/UCF system. Also note that if the USRIDXIT changes different CICS user-IDs to a common back-end ID, the security function of the USERCHK parameter does not work.The default is NO.
CICS Front-end JCL
To create a z/OS UCF CICS front-end program
  1. Create a UCFCICS source module as follows:
    ucfcicse #UCFCICS ucfcics-paramters END
  2. Save the UCFCICS source module in your custom source library.
  3. Assemble and link it into your custom load library by executing the z/OS Assemble and Link-Edit JCL.
    Substitute the name of your UCFCICS source member and insert the following binder statements:
    INCLUDE CAGJLOAD(UCFCICX0) INCLUDE CUSTLIB(
    ucffet
    ) INCLUDE CUSTLIB(
    idmscint
    ) INCLUDE CUSTLIB(
    ucfprint
    ) (optional) INCLUDE CUSTLIB(
    usridxit
    ) (optional) SETOPT PARM(AMODE=31,RMODE=24) ENTRY
    ucfcicse
    NAME ucfcics(R)
    • ucffet
      Specifies the name of your UCF front-end table.
    • idmscint
      Specifies the name of your IDMSCINT interface module.
    • ucfprint
      (Optional) Specifies the name of your UCFPRINT exit routine.
    • usridxit
      (Optional) Specifies the name of your USRIDXIT exit routine.
    • ucfcicse
      Specifies the entry point name of your UCFCICS options module:
      Note:
      Use UCFCXEP1 or the name that is specified as the label on the assembler instruction that invokes the #UCFCICS macro. The assembler label is optional. You cannot use UCFCXEP1 as the assembler label.
    • ucfcics
      Specifies the name of your UCF CICS front-end load module.
  4. Define program
    ucfcics
    in your CICS CSD.
    For a library template, see the definition of PROGRAM(UCFICS) in member CICSCSD of the CAGJSRC library. The program must be defined as RESIDENT.
z/VSE CICS front-end load module assembly
To create a z/VSE UCF CICS front-end program:
  1. Assemble and catalog the module using the sample JCL in z/VSE Assemble JCL.
    Modify the JCL by substituting the following statements in place of the
    Assembler input statements:
    PUNCH 'CATALOG
    ucfcics
    .OBJ REPLACE=YES' #UCFCICS #ucfcics-parameters END
  2. Link the
    ucfcics
    program using the sample JCL in z/VSE Link JCL.
    Modify the JCL by substituting the following statements in place of the
    Linkage editor control statements
    :
    PHASE
    ucfcics
    ,* INCLUDE DFHEAI INCLUDE ucfcics INCLUDE ucffet INCLUDE idmscint INCLUDE ucfprint (optional) INCLUDE usridxit (optional) INCLUDE DFHEAI0 MODE AMODE(31),RMODE(24) ENTRY ucfcicse
  3. Define program
    ucfcics
    in your CICS CSD.
    For a library template, see the definition of PROGRAM(UCFICS) in member CICSCSD of the CAGJSRC library. Define the program as RESIDENT.
    • ucffet
      Specifies the name of your UCF front-end table.
    • idmscint
      Specifies the name of your IDMSCINT interface module.
    • ucfprint
      (Optional) Specifies the name of your UCFPRINT exit routine.
    • usridxit
      (Optional) Specifies the name of your USRIDXIT exit routine.
    • ucfcicse
      Specifies the entry point name of your UCFCICS options module.
      Use UCFCXEP1 or the name that is specified as the label on the assembler instruction that invokes the #UCFCICS macro. The assembler label is optional. You cannot use UCFCXEP1 as the assembler label.
    • ucfcics
      Specifies the name of your UCF CICS front-end module.
CICS Front-end Execution
To execute the CICS front-end, you must add entries to the CICS CSD. See the definitions for PROGRAM UCFCICS and TRANSACTION(DBDC) in the source library that was created during CA IDMS installation.
Dedicated mode considerations
For the dedicated task,
task-code
must match the task code that is specified in the NTID parameter of the #UCFUFT macro that is used to create the CICS front-end table. The name
ucfcics
is the name of the CICS front-end module. The same module name should be used for all task codes, whether dedicated or intermittent.
Intermittent mode considerations
Each intermittent DC/UCF task that is defined in the CICS system must also be defined in the DC/UCF system with a TASK statement. The task code that is specified in the DC/UCF Sysgen must match the transaction name that is specified in the CICS CSD.
Entering the task code
Once defined to CICS and to the DC/UCF system, the CICS front-end can be executed by entering the dedicated task code or an intermittent task code.
Sample UCF definitions for CICS
Sample UCF system definition: The following examples show statements that define UCF with printer support on a CICS system. The CICS system has 12 terminals and 3 printers. The sample system uses sample programs UCFPRINT and UCFDESPL.
For more information about these programs, see Special CICS Considerations.
The sample system is defined as follows:
  • The UCF front-end table that defines devices to UCF
  • System generation LINE and PTERM statements that define devices to DC/UCF
  • Related CICS definitions
  • Related CICS definitions
For print devices, the same print-device names must be specified in the #UCFUTD macros that define the print devices (PRTA, PRTB, and PRTC in this example), in the PTERM statements that define the printers to DC/UCF, and in CICS printer definitions.
Sample UCF front-end table definition:
CICSFET #UCFUFT SYSTEM=CICS, X NTID=DBDC, *DEDICATED TASK ID X PTID=UCFP *PRINT TASK ID * DEFINE INTERACTIVE TERMINALS TO UCF #UCFUTD TERM=T001,TYPE=T3277,MODEL=2,PRTCLS=10 #UCFUTD TERM=T002,TYPE=T3277,MODEL=2,PRTCLS=10 #UCFUTD TERM=T003,TYPE=T3277,MODEL=2,PRTCLS=20 #UCFUTD TERM=T004,TYPE=T3277,MODEL=2,PRTCLS=30 #UCFUTD TERM=T005,TYPE=T3277,MODEL=2,PRTCLS=20 #UCFUTD TERM=T006,TYPE=T3277,MODEL=2,PRTCLS=10 #UCFUTD TERM=T007,TYPE=T3277,MODEL=2,PRTCLS=30 #UCFUTD TERM=T008,TYPE=T3277,MODEL=2,PRTCLS=30 #UCFUTD TERM=T009,TYPE=T3277,MODEL=2,PRTCLS=30 #UCFUTD TERM=T010,TYPE=T3277,MODEL=2,PRTCLS=10 #UCFUTD TERM=T011,TYPE=T3277,MODEL=2,PRTCLS=20 #UCFUTD TERM=T012,TYPE=T3277,MODEL=2,PRTCLS=20 * DEFINE PRINTER TERMINALS TO UCF #UCFUTD TERM=PRTA,TYPE=3280,FORMFD=NO #UCFUTD TERM=PRTB,TYPE=3280,FORMFD=YES #UCFUTD TERM=PRTC,TYPE=3280,FORMFD=YES
Sample DC/UCF system generation input
LINE UCF ENABLED TYPE IS UCFLINE MODULE IS RHDCFSTB. PTERM UCF01 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF01 . PTERM UCF02 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF02 . PTERM UCF03 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF03 . PTERM UCF04 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF04 . PTERM UCF05 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF05 . PTERM UCF06 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF06 . PTERM UCF07 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF07 . PTERM UCF08 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF08 . PTERM UCF09 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF09 . PTERM UCF10 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF10 . PTERM UCF11 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF11 . PTERM UCF12 ENABLED TYPE IS UCFTERM IN LINE UCF . LTERM UCF12 . * UCF PRINTERS PTERM UCFPRTA ENABLED TYPE IS UCFTERM IN LINE UCF NAME=PRTA LTERM UCFPRTA PRINTER CLASS =(10,11,12,13,14) . PTERM UCFPRTB ENABLED TYPE IS UCFTERM IN LINE UCF NAME=PRTB LTERM UCFPRTB PRINTER CLASS =(20,21,22,23,24) . PTERM UCFPRTC ENABLED TYPE IS UCFTERM IN LINE UCF NAME=PRTC LTERM UCFPRTC PRINTER CLASS =(30,31,32,33,34) .
Sample CICS generation input
DEFINE PROGRAM(UCFCICS) LANGUAGE ASSEMBLER CEDF(NO) EXECKEY(CICS) RESIDENT DEFINE PROGRAM(UCFDESPL) LANGUAGE ASSEMBLER DEFINE TRANSACTION(DBDC) PROGRAM(UCFCICS) DEFINE TRANSACTION(UCFD) PROGRAM(UCFDESPL) DEFINE TDQUEUE(PRTA) TYPE(INTRA) ATIFACILITY(TERMINAL) FACILITYID(PRTA) TRANSID(UCFD) TRIGGERLEVEL(1) DEFINE TDQUEUE(PRTB) TYPE(INTRA) ATIFACILITY(TERMINAL) FACILITYID(PRTB) TRANSID(UCFD) TRIGGERLEVEL(1) DEFINE TDQUEUE(PRTC) TYPE(INTRA) ATIFACILITY(TERMINAL) FACILITYID(PRTC) TRANSID(UCFD) TRIGGERLEVEL(1)
  • Transactions that invoke the UCFCICS program determine screen size characteristics by issuing an EXEC CICS ASSIGN command. You may want to associate these transactions with a PROFILE that specifies SCRNSIZE(ALTERNATE) to allow IDMS mapping applications to recognize the true device characteristics of the CICS terminals.
  • For more information about SCRNSIZE, see the relevant IBM documentation.
CICS Abort Session Program
The #UCFCICZ macro can be assembled to create an abort program to request UCF to abort the session for any terminal that disconnects or goes out of service. You can call the abort program by any combination of the following methods:
  • The CICS terminal error program DFHTEP
  • The node error program DFHZNEP
  • The bridge facility global exit XFAINTU
#UCFCICZ Macro
By using #UCFCICZ, you can assure the timely release of back-end resources when a front-end abort occurs. You can also prevent the following scenario from occurring:
A user signs onto CICS through a bridge facility or onto a VTAM terminal through a multisession manager. During a terminal-read request from UCF, the user loses the connection or terminates the CICS session from the multisession manager. A second user simultaneously connects and is assigned to the same terminal identifier. The second user invokes the UCF front-end program and is placed in the middle of the session started by the first user.
If either user signs onto CICS and the USERCHK=YES parameter is specified on the #UCFCICS macro, the situation that was described previously can also be avoided. For more information about the USERCHK parameter, see the section CICS Front-end.
A UCF CICS abort session program contains an options table and a small stub module that calls the main processing routines. Create the program by invoking the #UCFCICZ macro and linking it as shown in the diagram that follows.
Syntax
►►─── #UCFCICZ ───────────────────────────────────────────────────────────────► ►─── BRIDGE= ─┬─ YES ──┬─────────────────────────────────────────────────────► └─ NO ◄──┘ ►─── ERRDCT= ─┬─ CSMT ◄────────────┬─────────────────────────────────────────► └─ destination-name ─┘ ┌──────── , ────────┐ ►─── INTCID= ── ( ─▼─ intc-start-task ─┴ ) ──────────────────────────────────► ►─── MACLVL= ─┬─ YES ───┬────────────────────────────────────────────────────► └─ NO ◄───┘ ►─── NTID=dedicated-task-code ───────────────────────────────────────────────► ►─── OPSYS= ─┬─ MVS ◄──┬─────────────────────────────────────────────────────► └─ VSE ───┘ ►─── PASSVAL= ─┬─ TERMID ───┬────────────────────────────────────────────────► └─ TCTADDR ◄─┘ ►─── SQL= ─┬─ YES ──┬────────────────────────────────────────────────────────►◄ └─ NO ◄──┘
Parameters
  • BRIDGE
    Specifies whether the module that is generated by the #UCFCICZ macro is called from a program that is invoked by the bridge facility exit point XFAINTU. If NO is specified, the UCF abort session program assumes that the aborted session is associated with a permanent terminal. If UCFCICS had modified the UCTRANST value that is associated with the terminal, the UCF abort session program attempts to restore the original UCTRANST value. Therefore, if the associated UCFCICS macro specifies UCTRAN=TCT, this parameter has no effect. The default is NO.
  • ERRDCT
    Identifies the CICS transient data destination to be used as the target for error messages that are produced by IDMSINTC and IDMSTRUE. The default destination-name is CSMT. Use another destination if you want to route CA IDMS error messages to another CICS destination. The DCT entry should be defined with a logical record length of at least 130 characters.
  • INTCID
    Specifies the CICS transaction identifiers that are used to start each of the IDMSINTC interfaces. Use sublist notation when using more than one interface. When a lost terminal event occurs, each of these interfaces is notified so that it can sign the user off the respective IDMS system.
    If multiple #UCFCICZ macros are assembled with different NTID parameters, you must specify each IDMSINTC transaction identifier only once.
    Do not specify an INTCID transaction identifier for an IDMSINTC transaction which runs in a different region from the Terminal Owning Region (TOR).
  • MACLVL
    This parameter is obsolete. Macro level programs are no longer supported in CICS.
  • NTID
    Specifies the task code of the #UCFUFT macro that is used to create the CICS front-end table.
    If more than one UCFCICS front-end table exists (to communicate with more than one CA IDMS DC/UCF back-end), you must assemble and link edit separate CICZ modules. Each assembly should specify one NTID. Each CICZ module should be linked with a unique name.
  • PASSVAL=TCTADDR/TERMID
    Specifies the format and value of the COMMAREA parameter that is passed to the UCF abort session program. PASSVAL=TCTADDR indicates that the COMMAREA contains a fullword address pointing to the Terminal Control Table. PASSVAL=TERMID indicates that the COMMAREA contains the 4-byte identifier of the terminal or bridge facility that is associated with the aborted session.
    The default is TERMID.
  • SQL
    Specifies whether SQL suspended sessions are cleared by the abort session program. The default is NO.
How to Use the UCF CICS Abort Session Program
One or two UCF CICS abort sessions are needed for each UCFCICS program that is created with a #UCFUFT macro that specifies the corresponding NTID. One program is needed for persistent terminals. A separate one may be needed for sessions that are associated with a bridge facility.  If both the following conditions are true, a single program can be used:
  • All callers pass the same format COMMAREA to the UCF CICS abort session program as defined by the PASSVAL parameter. PASSVAL=TERMID is recommended.
    The recommended value is PASSVAL=TERMID, which is the default in Release 17.0 and later.
  • The associated #UCFCICS macro specifies UCTRAN=TCT.
For each UCF CICS abort session program you create, perform the following steps:
  1. Assemble the #UCFCICZ macro with the appropriate parameters and link the resulting program with a unique name
  2. Add an entry to the CICS CSD for each session abort program as follows:
    DEFINE PROGRAM(ucfcicz) GROUP(groupnam) LANGUAGE(ASSEMBLER) CEDF(NO) EXECKEY(CICS) RESIDENT
  3. Modify DFHTEP, DFHZNEP, and XFAINTU to call the appropriate versions of the program
Assemble and link edit #UCFCICZ
To assemble and link #UCFCICZ under z/OS:
  1. Create a UCFCICZ source module as follows:
    #UCFCICZ ucfcicz-parameters END
  2. Save the UCFCICZ source module in your custom source library.
  3. Assemble and link it into your custom load library by executing the z/OS Assemble and Link-edit JCL.
    Substitute the name of your UCFCICZ source member and insert the following binder statements:
    ORDER DFHEAI INCLUDE CICSLOAD(DFHEAI) INCLUDE CAGJLOAD(UCFCIZX0) INCLUDE CUSTLIB(
    idmscint
    ) INCLUDE CICSLOAD(DFHEAI0) ENTRY CICZEP SETOPT PARM(AMODE=31,REUS(NONE),RMODE=24) NAME ucfcicz(R)
    • idmscint
      Specifies the name of your IDMSCINT interface module.
    • ucfcicz
      Specifies the name of your UCF CICS abort session load module.
To assemble and link #UCFCICZ under z/VSE:
  1. Assemble and catalog the module using the sample JCL in z/VSE Assemble JCL.
    Modify the JCL by substituting the following statements in place of the
    Assembler input statements
    :
    PUNCH 'CATALOG
    ucfcicz
    .OBJ REPLACE=YES' #UCFCICZ #ucfcicz-parameters END
  2. Link the UCFCICZ program using the sample JCL in z/VSE Link JCL.
    Modify the JCL by substituting the following statements in place of the
    Linkage editor control statements
    :
    PHASE
    ucfcicz
    ,* INCLUDE DFHEAI INCLUDE ucfcicz INCLUDE ucfcizx6 INCLUDE idmscint INCLUDE DFHEAI0 MODE AMODE(31),RMODE(24) ENTRY CICZEP
    • idmscint
      Specifies the name of your IDMSCINT interface module.
    • ucfcicz
      Specifies the name of your UCF CICS abort session module.
Modify DFHTEP/DFHZNEP/XFAINTU to link to UCFCICZ
Modify the error programs or bridge facility tidy up program or both to link to the appropriate UCF session abort programs.
For more information about DFHTEP, DFHZNEP, and XFAINTU,refer to the CICS system documentation.
The following examples illustrate one approach to the modification of error and tidy up programs.
For DFHTEP and DFHZNEP, insert the instructions immediately before the DFHTEP/DFHZNEP exit. The logic states that if the error action codes indicate that the application task (if any) is to abend, a link is made to two UCF CICS session abort programs.
DFHTEP instructions when PASSVAL=TERMID
The following statements add instructions to DFHTEP when the #UCFCICZ macro specifies PASSVAL=TERMID:
TM TCTLEECB+1,X'04' ABEND TASK? BZ NOCICZ NO LA 10,TCTLEPTE POINTER TO TCTTE L 10,0(,10) TCTTETI EXEC CICS LINK PROGRAM('UCFCICZ1') COMMAREA( 0(10) ) LENGTH( 4). EXEC CICS LINK PROGRAM('UCFCICZ2') COMMAREA( 0(10) ) LENGTH( 4). NOCICZ DS 0H
DFHTEP instructions when PASSVAL=TCTADDR
The following statements add instructions to DFHTEP when the #UCFCICZ macro specifies PASSVAL=TCTADDR. This method is provided for compatibility with earlier versions. PASSVAL=TERMID is recommended.
TM TCTLEECB+1,X'04' ABEND TASK? BZ NOCICZ NO LA 10,TCTLEPTE POINTER TO TCTTE EXEC CICS LINK PROGRAM('UCFCICZ1') COMMAREA( 0(10) ) LENGTH( 4). EXEC CICS LINK PROGRAM('UCFCICZ2') COMMAREA( 0(10) ) LENGTH( 4). NOCICZ DS 0H
DFHZNEP instructions when PASSVAL=TERMID
The following statements add instructions to DFHZNEP when the #UCFCICZ macro specifies PASSVAL=TERMID:
TM TWAROPT2,TWAOAT ABEND TASK? BZ NOCICZ NO L 7,TWATCTA EXEC CICS LINK PROGRAM('UCFCICZ1') COMMAREA(0(7)) LENGTH( 4). * EXEC CICS LINK PROGRAM('UCFCICZ2') COMMAREA(0(7)) LENGTH( 4). NOCICZ DS 0H
DFHZNEP instructions when PASSVAL=TCTADDR
The following statements add instructions to DFHZNEP when the #UCFCICZ macro specifies PASSVAL=TCTADDR. This method is provided for compatibility with earlier versions. PASSVAL=TERMID is recommended.
TM TWAROPT2,TWAOAT ABEND TASK? BZ NOCICZ NO EXEC CICS LINK PROGRAM('UCFCICZ1') COMMAREA(TWATCTA) LENGTH( 4). * EXEC CICS LINK PROGRAM('UCFCICZ2') COMMAREA(TWATCTA) LENGTH( 4). NOCICZ DS 0H
XFAINTU instructions to invoke the session abort program
The following statements illustrate how to modify XFAINTU. The code should be executed only if UEPFAREQ contains the value UEPFATU on entry to XFAINTU.
EXEC CICS LINK PROGRAM('UCFCICZ1') COMMAREA(UEPFANAM) LENGTH( 4). * EXEC CICS LINK PROGRAM('UCFCICZ2') COMMAREA(UEPFANAM) LENGTH( 4).
DC Front-end
The UCF DC front-end enables a terminal on one DC system to execute tasks on a second DC system.
UCF DC front-end programs contain an options table and a small set of executable code that calls the main processing routines that reside in separate modules.
#UCFOPTS Macro
To create the DC front-end module, assemble a #UCFOPTS macro and link edit the resulting object module as shown in the following section.
Syntax
►►─── label #UCFOPTS ──────────────────────────────────────────────────────────► ►─┬─ CVNUM =
cv-number
, SVCNUM =
svc-number
─┬────────────────────────────────► └─ NODE =
nodename
,ACCTYPE= ─┬─ CCI ──────┤ ├─ VTAM ─────┤ ├─ TCP/IP ───┤ └─ TCPIP ────┘ ►─┬────────────────────┬───────────┬─────────────────────┬────────────────────►◄ └─ ,DISC= ─┬─ YES ─┬─┘ └─,FEONLY= ─┬─ YES ─┬─┘ └─ NO ◄─┘ └─ NO ◄─┘
Parameters
  • CVNUM=
    Identifies the DC/UCF back-end system. The value that is specified for cv-number must be the same value (0 through 255) specified by the CVNUMBER parameter of the system generation SYSTEM statement for the DC/UCF back-end system. For more information about the SYSTEM statement, see Using System Generation. If CVNUM is specified, SVCNUM must also be specified; NODE and ACCTYPE should not be specified.
  • SVCNUM=
    Specifies the number of the CA IDMS SVC through which the DC/UCF front-end system communicates with the DC/UCF back-end system. The value that is specified for svc-number should be an integer in the range 114 through 255.
  • NODE=
    Specifies the one- to eight-character name of  a DC/UCF system that is defined to  the DC/UCF DDS communication network. If NODE is specified, ACCTYPE must also be specified; CVNUM and SVCNUM should not be specified.
  • ACCTYPE=CCI|VTAM|TCP/IP|TCPIP
    Specifies the type of DDS communication to be used for the DC/UCF back-end system connection.
  • DISC=NO|YES
    Specifies the action the back-end DC/UCF system should take at the end of  an intermittent mode pseudo-converse. DISC=YES specifies that all DC/UCF back-end resources should be freed. DISC=NO specifies that the DC/UCF back-end terminal should be put in a SUSPEND state. The default is NO.
  • FEONLY=NO|YES
    Specifies whether the DC/UCF front-end module can also perform back-end functions. FEONLY=YES indicates that this module is used to perform front-end functions only. FEONLY=NO indicates that this module can perform both front-end and back-end functions. The default is NO.
    FEONLY=YES must be specified if a front-end module is to be used on one system to allow UCF terminals on that system to access another DC/UCF back-end system.
    Example:
    A CICS front-end accesses DC/UCF system 1 through UCF that uses a dedicated task code. At the ENTER NEXT TASK CODE prompt, the terminal operator enters task code DBDC2. This code is intended to connect to DC/UCF system 2 through UCF. Because the DC/UCF system 1 terminal is a UCF terminal, DBDC2 must invoke a front-end module that is generated with a specification of FEONLY=YES.
Assembly JCL
This section contains the JCL to create the DC front-end load module for z/OS, z/VSE, and z/VM operating systems.
To create a z/OS UCF DC front-end program:
  1. Create a UCFOPTS source module as follows:
    #UCFOPTS ucfopts-parameters END
  2. Save the UCFOPTS source module in your custom source library.
  3. Assemble and link it into your custom load library by executing the z/OS Assemble and Link-edit JCL.
    Substitute the name of your UCFOPTS source member and insert the following binder statements:
    INCLUDE CAGJLOAD(RHDCDBDC) INCLUDE CUSTLIB(
    ucffet
    ) INCLUDE CUSTLIB(
    ucfopts
    ) SETOPT PARM(AMODE=31) ENTRY DBDCEP1 NAME
    ucfdbdc
    (R)
    • ucffet
      Specifies the name of your UCF front-end table.
    • ucfopts
      Specifies the name of your UCFOPTS source module.
    • ucfdbdc
      Specifies the name of your UCF DC front-end load module.
To create a z/VSE UCF DC front-end program:
  1. Assemble and catalog the module using the sample JCL in z/VSE Assemble JCL.
    Modify the JCL by substituting the following statements in place of the
    Assembler input statements
    :
    PUNCH 'CATALOG ucfoptso.OBJ REPLACE=YES' #UCFOPTS ucfopts-parameters END
  2. Link the IDMSINTL interface program using the sample JCL in z/VSE Link JCL.
    Modify the JCL by substituting the following statements in place of the Linkage editor control statements:
    PHASE
    ucfdbdc
    ,* INCLUDE
    ucfoptso
    INCLUDE CUSTLIB(
    ucffet
    ) SETOPT PARM(AMODE=31,RMODE=ANY) ENTRY DBDCEP1
    • ucfoptso
      Specifies the name of your UCF DC options object module
z/VM DC front-end load module assembly
GLOBAL MACLIB idmslib FILEDEF TEXT DISK ucfdbdc TEXT A ASSEMBLE #ucfopts FILEDEF SYSLST PRINTER FILEDEF SYSLMOD DISK idmslib LOADLIB a2 (RECFM V LRECL 1024 BLKSIZE 1024 LKED linkctl
Linkage editor control statements (linkctl):
INCLUDE ucfopts INCLUDE RHDCUCFC INCLUDE RHDCDBDC INCLUDE ucffet ENTRY DBDCEP1 NAME ucfdbdc(R)
idmslib
filename of the CA IDMS MACLIB library
idmslib LOADLIB a2
file ID of the CA IDMS LOADLIB library
linkctl
filename of the file containing the linkage editor control statements
ucfdbdc
name of the DC front-end module
ucffet
name of the DC front-end table
#ucfopts
filename of the file containing the #UCFOPTS macro statement
ucfopts
name of the UCF options macro
DC Front-end Execution
To execute the DC front-end module, include the following system generation statements in the definition of the DC front-end:
  • A PROGRAM statement to define the DC front-end:
    ADD PROGRAM
    ucfdbdc
    LANGUAGE IS ASSEMBLER NOPROTECT NONREENTRANT.
    ucfdbdc
    is the name of the DC front-end module.
  • A TASK statement for the dedicated task code and one for each intermittent task code:
    ADD TASK
    task-code
    INVOKES PROGRAM
    ucfdbdc
    INPUT.
Dedicated mode considerations
For the dedicated task,
task-code
must match the task code that is specified in the NTID parameter of the #UCFUFT macro that is used to create the DC front-end table.
ucfdbdc
is the name of the DC front-end module; use the same module name for all task codes, whether dedicated or intermittent.
Intermittent mode considerations
Each intermittent task that is defined in the DC front-end system must also be defined in the DC/UCF back-end with a TASK statement. The specified task code must match the task code that is specified in the DC front-end system definition.
TSO Front-end
The UCF TSO front-end enables DC/UCF tasks to be executed from a terminal that is connected to TSO.
UCF TSO front-end programs contain an options table and a small set of executable code that calls the main processing routines that reside in separate modules.
To create the TSO front-end program, assemble a #UCFTSO macro and link edit the resulting object module as shown in the following section.
The TSO front-end supports dedicated mode only and requires no front-end table definition.
IDMSOPTI
The IDMSOPTI module identifies the back-end system with which the front-end communicates. The module is created by assembling an IDMSOPTI macro. If you omit IDMSOPTI from the link edit of the front-end system, the execution JCL for the front-end must include a SYSCTL file that identifies the back-end system.
  • The TSO front-end load modules link edit into the CA IDMS load library during installation. Module RHDCUCFT is used for traditional UCFTSO, and RHDCUCFL is used through a command line interface, for example the Zowe CLI. You should reassemble and relink edit the modules only if the default options need to be changed.
For more information about IDMSOPTI, see Setting Up Interpartition Communication and the SVC.
#UCFTSO Macro
Syntax for the #UCFTSO macro follows. The macro must be labeled.
Syntax
►►───
label
#UCFTSO ──────────────────────────────────────────────────────────► ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ BREAKIN = ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬────────────────────┬─────────────────────────────────────────────────────► └─ CLI = ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬──────────────────────────────────────┬───────────────────────────────────► └─ ,RSHWKEY = ─┬─ 24 ◄───────────────┬─┘ └─
reshow-key-number
─┘ ►─┬───────────────────────────────────────┬──────────────────────────────────► └─ ,SYSTEM = ─┬─ TSO ◄────────────────┬─┘ └─
front-end-system-id
─┘ ►─┬──────────────────────┬───────────────────────────────────────────────────► └─ ,TONE = ─┬─ YES ──┬─┘ └─ NO ◄──┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ ,VTAM = ─┬─ YES ◄───┬─┘ └─ NO ─────┘ ►─┬───────────────────────────────┬──────────────────────────────────────────► └─ ,BUFSIZ = ─┬─ 0 ◄──────────┬─┘ └─
buffer-size
─┘ ►─┬─────────────────────────────┬────────────────────────────────────────────► └─ ,RESETKB = ─┬─ ASIS ◄────┬─┘ └─ TASKEND ──┘ ►─┬─────────────────────────┬────────────────────────────────────────────────► └─ ,OPSYS = ─── MVS ◄─────┘ ►─┬────────────────────────┬─────────────────────────────────────────────────►◄ └─ , TCAM = ─┬─ YES ───┬─┘ └─ NO ◄───┘
Parameters
  • SYSTEM=
    Specifies the one- through eight-character identifier of the TSO front-end.
    front-end-system-id
    must match the identifier that is specified in the FESID parameter of the #FESTENT macro that is used to define the TSO front-end system in the UCF system table (described under #FESTENT Macro). TSO, the default, matches the FESID value for the TSO front-end supplied with the UCF system.
  • BREAKIN=NO|YES
    Specifies whether the front-end uses the BREAKIN option when issuing TPUTS to non-3270 terminals. The default is NO.
  • CLI=YES/NO
    Specifies whether a command line interface, for example the Zowe CLI, is used with UCFTSO to interact with the backend system.
    Default:
    NO
  • RSHWKEY=
    Specifies the value of the function key that is used by TSO to queue a dummy input when a UCF TSO session is interrupted by a message from the operator or by notification. The dummy input (PF1 through PF24 or PA2) signals the front-end program to try to reshow the screen that was displayed before the interruption.
    reshow-key-number
    must be 64 or an integer in the range 1 through 24; the default is 24. The value 64 corresponds with PA2; 1 corresponds with PF1, and so on.
  • TONE=NO|YES
    Specifies whether the front-end program runs under TONE rather than TSO; the default is NO. If YES is specified, the program issues STAX macros rather than STTMPMD macros.
  • VTAM=NO|YES
    Specifies whether TSO runs under ACF/VTAM; the default is YES. If YES is specified, the TSO front-end can issue GTTERM macros to determine if a 3279-type color terminal with extended data screen support is being used. The TSO front-end uses the TPG macro to execute 3270 read-buffer operations that support the UCF print-key facility.
  • BUFSIZ=
    When VTAM=YES is specified, GTTERM macro is used to obtain the terminal screen size. Buffer size is calculated to be 1.5 times the terminal screen size, plus a small amount of padding. This calculated amount is compared to any BUFSIZ specification (the default is 0). The higher value of the two is used. The calculated size is typically sufficient for processing. IBM 3270-type terminals using extended (color) data streams, or MAPs having many fields may need more buffer space. BUFSIZ may be used to increase the buffer space allocation.
  • RESETKB=
    Specifies whether the terminal keyboard is reset after each terminal write. Default is 'ASIS,' where the keyboard is reset after each terminal write. An occasional 'X-F' (input inhibit) may still appear, however. If 'TASKEND' is specified, the keyboard is reset only at end of task. This reset causes one extra terminal write per task, but eliminates the occasional input inhibit. This may be of particular value in an IDBCOMM environment.
  • OPSYS=
    Default is MVS. The STTMPMD macro does not contain the same parameters as the IBM version.
  • TCAM=NO|YES
    Specifies whether TSO runs under TCAM. The default is NO. If TCAM=YES is specified, VTAM=NO is required. TCAM is no longer a supported monitor.
Assembly JCL
This section contains the JCL to create the TSO front-end load module for z/OS.
To create a TSO front-end load module assembly
  1. Create a UCFTSO source module as follows:
    #UCFTSO ucftso-parameters END
  2. Save the UCFTSO source module in your custom source library.
  3. Assemble and link it into your custom load library by executing the z/OS Assemble and Link-Edit JCL.
    Substitute the name of your UCFTSO source member and insert the following binder statements:
    INCLUDE CUSTLIB(
    idmsopti
    ) ENTRY UCFTSOX SETOPT PARM(REUS=NONE,AMODE=31,RMODE=24) NAME ucftso(R)
    • idmsopti
      (Optional) Specifies the name of your IDMSOPTI module.
    • ucftso
      Specifies the name of your UCF TSO front-end load module.
Front-end execution
To execute the TSO front-end, use the TSO CALL verb, as follows:
CALL '
your-custom-loadlib(ucftso)
'
When the terminal emulator alternate display size is not a standard 3270 model (Mod2 – Mod5), the TSO front-end uses the emulator default display size. In this case, the default display size can be either 3270 Mod2, Mod3, or Mod4. To display properly, the TSO front-end should be aligned with the default or primary display size of the emulator.
To align with the default or primary display size of the emulator, supply a parameter to the TSO front-end:
CALL '
your-custom-loadlib(ucftso)
' ‘
DFLTSIZ=value
Values recognized by the TSO front-end are 24X80, 32X80, 43X80, MOD2, MOD3, or MOD4. If not specified, a 3270 MOD2 (24X80) is assumed.
CALL can also be invoked through a TSO CLIST.
The UCF CLIST should contain an ALLOC statement for FILE(SYSIDMS), which points to the SYSIDMS file containing the CVRETRY=OFF parameter. This parameter causes an error to be returned to the program if the back-end system is not active. An example of a UCFTSO CLIST can be found in the sample JCL library offloaded at install time as member UCFTSOCL.