C H A P T E R  2

System Transactions

Sun MTP provides a set of transactions for system control and access to the Development System. These transactions are known as system transactions.

This chapter includes the following topics:


Overview of the System Transactions

The following transactions are used for control and debugging:

Transaction

Usage

CBCH

Online batch execution

CEBR

Browse temporary storage

CECI

Interactively execute CICS commands

CEDA

Dynamically manipulate resource definitions

CEDF

Execute debug facility

CEMT

Set/display status

CINI

Reinitialize transaction servers

CRTE

Route transactions from the Sun MTP region

CSMT

System termination

CSPG

System paging

CESN
CSSN

Sign-on

CESF
CSSF

Sign-off


The following transactions are used internally by Sun MTP. See Security for Sun MTP System Transactions.

Transaction

Usage

CCIN

CICS client transaction

CPLT

Initializes PLT processing

CPMI

LU6.2 mirror transaction

CRSR

Intersystem communications (ISC) remote scheduler transaction

CTIN

CICS client transaction

CVMI

LU6.2 synclevel 1 mirror transaction


The following transactions provide direct access to parts of the Development System If transaction security is enabled, access to these transactions should be restricted because end users do not need to use any of the direct access transactions. See Administering Transaction Security.

CFMS

File Manager

CMNU

Development System main menu. Only available from locally connected terminals. Not available on TN3270 connections.

CRED

Record Editor

CSGU

Screen Generation Utility (SGU)

CTBL

Table Manager




Note - If you are using Micro Focus Animator, CodeWatch, or a C/C++ debugger, use the CEDF transaction to turn off the source debugger before executing any other system transaction.




CBCH - Online Batch Execution

Use the CBCH transaction to execute batch programs or shell scripts immediately from the online environment for any program type. This transaction overrides the normal priority calculation used to automatically execute batch programs or shell scripts, and starts them as if they are a foreground transaction.

Format:

CBCH program

where program is the absolute or relative path name of the batch program or shell script to start. The batch program or shell script executes out of the directory defined by the KIXSYS environment variable. If a relative path is entered, it is relative to the $KIXSYS directory.



Note - You cannot execute batch programs or shell scripts with the CBCH transaction if the system is set to BATCH state with CEMT SET. See Setting the System State.



CBCH can be used with the CEDF transaction using the Animator option to debug batch COBOL programs. To debug a batch program, you must invoke the program in a batch shell script using the -D parameter of unikixvsam, the COBOL runtime system. For more information about batch programming and debugging, refer to the Sun Mainframe Transaction Processing Software Developer's Guide.

The CEDF transaction is briefly described in CEDF - Execute Debug Facility and in more detail in the Sun Mainframe Transaction Processing Software Developer's Guide.


CEBR - Browse Temporary Storage

Use the CEBR transaction to browse temporary storage and to retrieve and insert data into intrapartition queues.

To start, type the CEBR transaction; no parameters are accepted. To terminate the transaction, press PF3.

When the transaction starts, it defaults the initial temporary storage queue to CEBRxxxx, where xxxx is equal to the terminal identifier of the terminal issuing the request.

The following figure shows the default CEBR screen.

  FIGURE 2-1 CEBR - Browse Utility--Default Screen

Screen shot showing the CEBR transaction screen.

After CEBR starts, it accepts commands both on a command line and by using the PF keys. The information displayed on the screen depends on the data written to the viewed queue.

CEBR accepts the following commands on the command line:

BOTTOM or B

Positions the display to the bottom of the queue. Press PF7 to page back through the queue.

COLUMN or C

Positions the display to the specified column. For example, if the displayed queue has entries longer than 79 characters (39 in hexadecimal), only the first 79 (or 39) characters are displayed for each entry. To display additional characters in the queue entries, set the column number to the position to display.

FIND or F

Searches the queue for the specified string. If the specified string starts with a special character, such as "/", it is taken as a string terminator and the transaction searches for the matching end of string terminator. Otherwise, the first blank terminates the string.

CEBR always converts input to uppercase. Therefore, it cannot search for strings that contain lowercase characters. When CEBR finds the string, it repositions the queue display so the first line and first column are equal to the start of the string.

GET or G

Moves an intrapartition queue into the current temporary storage queue. Enter the queue name with the GET command to specify the transient data queue.

LINE or L

Displays the specified line on the second line of the screen.

PURGE

Deletes the current temporary storage queue.

PUT or P

Moves the current temporary storage queue into the specified transient data queue.

QUEUE or Q

Changes the current queue to the queue specified.

TERMINAL or TERM

Changes the current queue to CEBRxxxx, where xxxx is the parameter specified.

TOP or T

Positions the display to the first entry in the queue. Press PF8 to page forward through the queue.


These function keys are active while in the CEBR transaction:

PF1

Displays a list of valid command-line commands.

PF2

Switches the display from character to hexadecimal or from hexadecimal to character.

PF3

Ends the CEBR transaction.

PF4

Positions the display to the first entry in the queue.

PF5

Positions the display to the last entry in the queue.

PF6

Searches for the next occurrence of the previous find command.

PF7

Positions the current line pointer back one-half page.

PF8

Positions the current line pointer forward one-half page.

PF10

Positions the current line pointer back a full page.

PF11

Positions the current line pointer forward a full page.



CECI - Command Interpreter

The CECI transaction enables you to interactively execute CICS commands from a 3270 terminal window in a manner similar to that allowed by the IBM CICS CECI transaction.


procedure icon  To Start the CECI Interpreter

single-step bulletType the transaction identifier CECI on a blank transaction screen.

The Commands screen is displayed, listing the supported CICS commands.

  FIGURE 2-2 CECI --Commands Screen

Screen shot showing the CECI screen with supported commands. Message at bottom of screen prompts to enter an API command.

The following function keys are active on the CECI Commands screen:

PF3

Returns to the previous screen.

PF4

Displays the Exec Interface Block.

PF5

Displays user-defined variables.

PF6

Displays the user screen generated by a command.

PF7

Scrolls back a full page.

PF8

Scrolls forward a full page.

Enter

Displays the Syntax screen for the selected command.


Defining and Executing CECI Commands

This section describes the CECI screens and how to use them to define and execute commands.

Commands Screen

The CECI Commands screen displays the Sun MTP-supported commands. On this screen you can:

Syntax Screen

When the Syntax screen is displayed, it lists the command you selected on the Commands screen or that you entered when you executed the CECI transaction at a blank transaction screen. The STATUS indicator on line 19 of the screen displays: Command Syntax Check.

This section describes how to create and execute a command from CECI. It also points to sections that describe other screens you can use as you build and execute commands. See also the information in the following sections, which describe how CECI manages arguments and the program control you can expect from certain commands.

The following figure shows the Syntax screen after you select the GETMAIN command. Note that the status is Command syntax check.

  FIGURE 2-3 CECI --Syntax Screen (Command syntax check)

Screen shot showing the CECI syntax screen for the GETMAN command.

The Syntax screen uses the following symbols:

Symbol

Description

[ ]

You can, but do not have to, include these options.

( )

This option takes an argument.

Boldface

Options in the option list appear in bold after you type them on the command line. The command line is also in bold.


The following function keys are active on the CECI Syntax screens:

PF2

Toggles the display from character/decimal (the default) to hexadecimal. When labeled Char/Decimal, changes the display from hexadecimal to character/decimal.

PF3

Returns to the previous screen.

PF4

Displays the Exec Interface Block.

PF5

Displays user-defined variables.

PF6

Displays the screen captured by CECI after you execute a command that sends 3270 data to a terminal screen. See User Screen.

PF7

Scrolls back a full page.

PF8

Scrolls forward a full page.

PF9

Displays the Messages screen, which lists any diagnostic messages issued by the translator. See Messages Screen.

Enter

Displays the next screen of the Syntax sequence, eventually executing the command. See the procedures to create and execute a command.



procedure icon  To Create and Execute a Command

1. On the Commands Screen, type a command such as GETMAIN, and press Enter.

The Syntax Screen is displayed with the CECI GETMAIN command. Note that the STATUS is Command syntax check.

2. Create the command line.

a. Type one or more options and arguments on the command line.

You can press Enter after each option or wait until typing all the options.

b. While creating the command, you can press PF5 to display the Variables screen where you can define or view variables, such as &MYSET.

See Variables Screen for more information about defining variables.

c. While creating the command, press PF2 to toggle between hexadecimal and character/decimal display of variable values.

d. Repeat these procedures as many times as necessary to build the complete command.

e. When you finish creating the command, press Enter.

FIGURE 2-4 shows a complete command.

  FIGURE 2-4 CECI --Syntax Screen (Command syntax check)

Screen shot showing the CECI syntax screen with a complete GETMAIN command.

3. Translate the command.

a. When the command line is complete, press Enter again to pass the command to the translator.

If the translation is successful, the STATUS field on the Syntax screen changes to About to execute command. Note that the options you selected appear in bold. See FIGURE 2-5.

b. Press PF9 to view any messages generated by the translator.

  FIGURE 2-5 CECI --Syntax Screen (About to execute command)

Screen shot showing the CECI syntax screen after the GETMAIN command string has been translated.

4. At this point, you can either:

  FIGURE 2-6 CECI --Syntax Screen (Command executed)

Screen shot showing the CECI syntax screen after the GETMAIN command has executed successfully.

5. After the command executes, you can:

Hexadecimal Display Screen

You can view the Syntax and Variables screens in character (default) and hexadecimal modes. Press PF2 to toggle the display mode. When you are in hexadecimal mode on the Variables screen, a display mode indicator is displayed in the lower right corner of the screen.

In hexadecimal mode you can define or view variables that contain bytes of data whose hexadecimal value does not correspond to an ASCII printable character.

In character mode, CECI displays bytes whose values do not correspond to a printable character, such as a period (.). In character mode, you cannot update such a variable byte with a period. To replace a variable byte whose hexadecimal value represents a non-printable character with a period, switch to hexadecimal mode and insert the ASCII code for a period (x'2d').

The following figure shows the Variables screen in hexadecimal display mode.

  FIGURE 2-7 CECI --Variables Screen (Hexadecimal Display Mode)

Screen shot showing the CECI variables screen for the GETMAIN command in hexadecimal mode.

On a screen that allows hexadecimal display mode, the PF2 key is labeled as follows:

Hexadecimal

Toggles the display from character/decimal (the default) to hexadecimal mode.

Char/Decimal

Toggles the display from hexadecimal to character/decimal mode.


EIB Screen

You can view data in the EIB at any time during a CECI session by pressing PF4 on the Commands or Syntax screens. FIGURE 2-8 shows the EIB screen.

Press PF3 to return to the previous screen.

  FIGURE 2-8 CECI --EIB Screen

Screen shot showing the CECI Exec Interface Block screen. The PF3 function key is active on this screen. It returns to the previous screen.

Variables Screen

CECI allows you to define variables to use as option arguments in the command syntax. Because the lifetime of the variables you define is equal to the duration of the CECI session, you can use them to carry forward data returned from the execution of one command to subsequent commands.

After you define a variable, you can use it in a command line. When the command syntax is expanded, the value of the variable is substituted for the variable name. Any change to a variable value during execution of the command is reflected on the Syntax and Variables screens.

An example of each variable type is defined when CECI is initialized. You can view the examples by pressing PF5 on the Commands or Syntax screens. The following figure shows a Variables screen (in character/decimal mode) that has the five pre-defined variables and a user-defined variable named &MYSET.

  FIGURE 2-9 CECI --Variables Screen

Screen shot showing the CECI variables screen for the GETMAIN command in character/decimal mode.

The following function keys are active on the Variables screen:

PF2

Toggles the display from character/decimal (the default) to hexadecimal.

PF3

Returns to the previous screen. If you press PF3 without pressing Enter, any changes you made on the Variables screen are lost.

PF10

Opens the Edit Variables screen, described in Edit Variable Screen.

Enter

You can press the Enter key after making any change on the Variables screen or you can press it once at the end of the Variables screen session to process all changes.


On the Variables screen, you can define, delete, and modify CECI variables.


procedure icon  To Add a Variable

1. Position the cursor at the start of the next available Name field.

2. Type the variable name, which can be a maximum of 9 characters: A-Z, a-z,
0-9, and must start with an ampersand (&) character.

3. Tab to the Length column and type the abbreviation for the type or a numeric length.

If you specify an abbreviation, the length is inserted automatically. TABLE 2-1 defines the variable types.

4. Press Enter.


procedure icon  To Delete a Variable

1. Type over the variable name field with blanks.

You can delete any variable, including those supplied with Sun MTP.

2. Press Enter.


procedure icon  To Modify a Variable

1. Type over any field with the new value.

2. Press Enter.



Note - When adding or modifying variables whose lengths are greater than 40 bytes (20 bytes when the display mode is hexadecimal), you must use the Edit Variable screen described in Edit Variable Screen.



The following table defines the variable types.

TABLE 2-1 CECI Variable Types

Type

Length
(Bytes)

Abbreviation

Example

Halfword

2

H

04321

Fullword

4

F

0001234567

Packed Decimal

4

P

4000010C

Doubleword

8

D

00ABCDE126395417

Buffer

Maximum 32767

Numeric length

Example Buffer


Edit Variable Screen

The Edit Variable screen enables you to edit user-defined variables in full screen mode. You can edit all variable types on this screen. You must use this screen to edit Buffer variables whose lengths are greater than the 40-byte limitation of the Variables screen (20 bytes when the display mode is hexadecimal).


procedure icon  To Edit a Variable

1. On the Variables screen, position the cursor on a line containing the variable to edit.

2. Press PF10 to display the Edit Variable screen.

3. Modify the variable.

4. Press Enter to accept the change.

5. Press PF3 to return to the Variables screen.

The following figure shows the Edit Variable screen.

  FIGURE 2-10 CECI --Edit Variable Screen

Screen shot showing the CECI screen used to edit variables.

The following function keys are active on the Edit Variable screen:

PF2

Toggles the display from character/decimal (the default) to hexadecimal. When labeled Decimal/Char, switches the screen from hexadecimal to character/decimal.

PF3

Returns to the previous screen.

PF7

Scrolls back a full page.

PF8

Scrolls forward a full page.


User Screen

After you execute a command, such as SEND MAP, that sends 3270 data to the terminal screen, CECI captures the screen. You can display the screen by pressing PF6 on either the Commands or Syntax screens. Press any key to return to the previous screen.

The following figure shows the User screen captured after executing the following command string:

CECI SEND MAP(ACCTMNU) MAPSET(ACCTSET) MAPONLY



Note - The ACCTMNU BMS map is in the ACCTSET BMS mapset in the Sun MTP Primer region.



  FIGURE 2-11 CECI --User Screen

Screen shot showing the CECI user screen, which is the screen that a user would see if the command was executed in a production environment.

Messages Screen

Before executing a command, CECI invokes a translator that checks the syntax of the command line. If the translator detects an error, it displays the following message on the Syntax screen:

KIX3220E Translation Error - see PF9.

You can view diagnostic messages by pressing PF9.

The Translator Diagnostic Messages screen shown in FIGURE 2-12 shows the message generated by the following incorrect command:

CECI STARTBR DAXASET(ACCTIX)

Notice the misspelling of DATASET as DAXASET.

Press PF3 to return to the previous screen.

  FIGURE 2-12 CECI --Translator Diagnostic Messages Screen

Screen shot showing the CECI Translator Diagnostic Messages screen.

Dynamic Receiver Arguments

When data is flowing into an option field, CECI can dynamically allocate the storage for that variable. This means you do not have to define all variables on the Variables screen.



Note - Dynamically allocated variables are transient and the data received is not available for use on subsequent commands. Also, you cannot edit these variables on the Edit Variable screen.



Before CECI can dynamically allocate storage for a receiver variable, you must specify the option on the command line. The option must be terminated by an empty pair of parentheses, as illustrated in this example:

CECI READ DATASET(ACCTIX) INTO() RIDFLD(&KEY) LENGTH(63)

When this command executes, CECI dynamically allocates a receiver variable for the INTO() option.

Literal Option Arguments

Another way to pass data without creating a CECI variable is by specifying option arguments as literals.

Program Control

This section describes the program control policy for CECI with the LINK, XCTL, and ABEND commands.

LINK

Control returns to CECI following execution of a LINK command.

XCTL

Control never returns after an XCTL command and the current CECI session terminates. Not supported in this release.

ABEND

With the CANCEL option, ABEND terminates the CECI session. With or without the CANCEL option, ABEND processing is completed, including recovery of protected resources.


Logical Units of Work

CECI is a conversational transaction and, by default, all commands executed within any CECI session are contained within a single Logical Unit of Work (LUW). You can manage LUWs within a single CECI session by using the SYNCPOINT and ROLLBACK commands.


CEDA - Manipulate Resources

The CEDA transaction is used to dynamically manipulate resource definitions. Its options are described in the following subsections.

For more information about managing resources dynamically, refer to the Sun Mainframe Transaction Processing Software Configuration Guide.



Note - For most attribute values, the text you type is converted to uppercase. The exceptions to this are the values for GROUP, DESCRIPTION, JVMCLASS, and SHLIB, which support mixed case.



DEFINE Option

The CEDA DEFINE option allows you to define a resource. In the current release, mapsets, programs, and transactions are supported.

Format:

CEDA DEFINE GROUP(group-name)
[MAPSET(
mapset-name)[attribute(value)] ... |
PROGRAM(program-name) [attribute(value)]... |
TRANSACTION(transaction-name) [attribute(value)]]

where:

GROUP(group-name)

Name of the group to which to add this mapset; up to eight characters without embedded spaces. If the group does not exist, it is created. Text can be mixed case.

MAPSET(mapset-name)

Name of the mapset; up to eight characters without embedded spaces. Do not use any system-supplied program or mapset names beginning with C. Lowercase characters are converted to uppercase.

PROGRAM(program-name)

Name of the program; up to eight characters without embedded spaces. Do not use any system-supplied program or mapset names beginning with C. Lowercase characters are converted to uppercase.

TRANSACTION(transaction-name)

Name of the transaction; up to 4 characters without embedded spaces. Do not use any system-supplied program or mapset names beginning with C. Lowercase characters are converted to uppercase.

attribute(value)...

The attributes of the resource. See the following sections for descriptions of the attributes.


MAPSET Attributes

The supported MAPSET attributes are:

[DESCRIPTION(description)]

[STATUS(ENABLED|DISABLED)]

where:

DESCRIPTION(description)

Description of the mapset; up to 58 characters. Text can be mixed case.

STATUS(ENABLED|DISABLED)

Specifies the mapset's status. ENABLED is the default.


Example: To define the mapset, INVADD01, that is in the CMP1INV group, type the following on a blank transaction screen:

CEDA DEFINE GROUP(CMP1INV) MAPSET(INVADD01)

PROGRAM Attributes

The supported PROGRAM attributes are:

[DESCRIPTION(description)]

[LANGUAGE([ASSEMBLER|C|COBOL|PLI])]

[STATUS(ENABLED|DISABLED)]

where:

DESCRIPTION(description)

Description of the program; up to 58 characters; optional. Text can be mixed case.

LANGUAGE ([ASSEMBER|C|COBOL|PLI])

Name of the programming language. If not specified, the default is COBOL.

  • ASSEMBLER: Table referenced by application programs using CICS LOAD and CICS RELEASE commands
  • C: C language
  • COBOL: COBOL language
  • PL/I: PL/I language

STATUS(ENABLED|DISABLED)

Specifies the program's status. ENABLED is the default.


Remote attributes:

[EXECUTIONSET(FULLAPI|DPLSUBSET)]

[REMOTENAME(program-name)]

[REMOTESYSTEM(system-name)]

[TRANSID(transaction-name)]

where:

EXECUTIONSET (FULLAPI|DPLSUBSET)

If the REMOTESYSTEM name is the same as the local system name, then EXECUTIONSET specifies to run the DPL program in the local system as if it were a remote system. See Chapter 6 for additional information.

  • FULLAPI: The program can use all the CICS API commands. Default.
  • DPLSUBSET: The program cannot use any DPL-restricted API.

REMOTENAME(program-name)

Name of the program in the remote Sun MTP or CICS system. If REMOTENAME is not specified and REMOTESYSTEM is specified, then Sun MTP assumes PROGRAM name. See Chapter 6 for additional information. program-name is limited to eight characters.

REMOTESYSTEM(system-name)

Name of the remote Sun MTP or CICS system to which, if specified, Sun MTP will ship a distributed program link (DPL) request. The 4-character system-name must be in TCT-System Entries table.

TRANSID(transaction-name)

Name of the transaction under which the remote system attaches the requested program. See Chapter 6 for additional information.


Java virtual machine (JVMtrademark) attribute:

[JVMCLASS(class-name)]

where:

JVMCLASS(class-name)

Name of the main class of the Java program; maximum of 256 characters. Class name can be mixed case.


Sun MTP attributes:

[PRELOAD(NO|YES)]

[SHLIB (shared-library-name)]

where:

PRELOAD(NO|YES)

Indicates if the transaction server should open the shared library at startup.

SHLIB(shared-library-name)

Name of the shared library, up to 16 characters, which contains the specified program. All entries are relative to $KIXSYS unless the KIXLIB environment variable is set to a path name. Name of shared library can be mixed case.


Example: To define the inventory add program, INVPGM1, that is in the CMP1INV group, type the following on a blank transaction screen:

CEDA DEFINE GROUP(CMP1INV) PROGRAM(INVPGM1) DESCRIPTION(Inventory add program)



Note - If the command is too long to fit on one line, it wraps automatically; no continuation character is needed.



TRANSACTION Attributes

The supported TRANSACTION attributes are:

[DESCRIPTION(description)]

[PROGRAM(program-name)]

[TWASIZE(0-32767)]

[STATUS(ENABLED|DISABLED)]

where:

DESCRIPTION(description)

Description of the transaction; up to 58 characters; optional. Text can be mixed case.

PROGRAM(program-name)

Program name. Lowercase characters are treated as uppercase.

TWASIZE(0-32767)

Transaction Work Area (TWA) size in bytes.

STATUS(ENABLED|DISABLED)

Specifies the transaction's status. ENABLED is the default.


Remote attributes:

[LOCALQ(NO|YES)]

[REMOTESYSTEM(system-name)]

[REMOTENAME(program-name)]

where:

LOCALQ(NO|YES)

Indicates whether transactions shipped to a remote system are locally queued if the remote system is unavailable. Default is NO.

REMOTENAME(program-name)

Name of the program in the remote Sun MTP or CICS system. If REMOTENAME is not specified and REMOTESYSTEM is specified, then Sun MTP assumes PROGRAM name. See Chapter 6 for additional information. program-name is limited to eight characters.

REMOTESYSTEM(system-name)

Name of the remote Sun MTP or CICS system to which, if specified, Sun MTP will ship a distributed program link (DPL) request. The 4-character system-name must be in TCT-System Entries table.


Scheduling attribute:

[TRANCLASS(transaction-class)]

where:

TRANCLASS(transaction-class)

Name of the transaction class to which the transaction is assigned.


Recovery attribute:

[DUMP(YES|NO)]

where:

DUMP(YES|NO)

Indicates whether a transaction dump will be produced if the transaction terminates abnormally. Default is YES.


The following attributes are specific to Sun MTP and are not part of the IBM CICS set:

[SCREENSIZE(DEF|ALT)]

[ACCOUNTING(DEF|NO|YES)]

[FILEID(0-99)]

[APPC(YES|NO)]

[TASKREQKEY(value)]

[TRANSEC(1-64)]

where:

SCREENSIZE(DEF|ALT)

Default screen size or the alternate screen size.

DEF: Default screen size of 24 lines and 80 columns for Model 2 3270 terminal types

ALT: Alternate screen sizes of 27 lines and 132 columns for Model 5 3270 terminal types, or 43 lines and 80 columns for Model 4 3270 terminal types

ACCOUNTING(DEF|NO|YES)

Indicates whether accounting is on or off for this transaction.

YES: Accounting is on for this transaction, if the Accounting field in the SIT is set to Y

NO: Accounting is off for this transaction

DEF: (Default) Accounting is controlled by the SIT Accounting field and the MCT

FILEID(0-99)

Journal file identifier for this transaction; a number from 1 to 99. If accounting is set to N, this field is ignored.

If file ID is not specified in the JCT, the journal file name is created by concatenating JRNL with the file ID value, creating, for example, a journal file named JRNL05.

APPC(YES|NO)

Back-end DTP transaction.

YES: Transaction is a back-end DTP program and performs ISC functions.

NO: Transaction is not a back-end DTP program. It can still perform outbound ISC functions, but does not run as expected if started by a remote Sun MTP or CICS region.

TASKREQKEY(value)

Key that initiates this program as a transaction. If this field is blank, no key initiates this program as a transaction. Valid values are:

PF1 through PF24

PA1 through PA3

TRANSEC(1-64)

A number from 1 to 64 specifying a transaction security level. This value corresponds to a bit value set in the Security Key area of the SNT associated with the user at the terminal that entered the transaction.

If external security management is enabled (KIXSEC=YES), the value in Trans Sec is ignored.

The Security Key is set for a user by the SNT when the user signs on explicitly with CSSN (CESN), or implicitly when Sun MTP starts and a match is found between the user ID and a user ID in the SNT. By default, each user is only allowed to enter transactions with a security level of 1. All system transactions are set initially to a transaction security level of 1, which allows all users to access them.

Raise the security level for critical transactions, such as CSMT, CEMT and other transactions that are used to configure the Sun MTP environment to prevent unauthorized users from accessing them. See Chapter 7 for information about Sun MTP security.


DELETE Option

The DELETE option deletes a resource.

Format:

CEDA DELETE ALL | [MAPSET(mapset-name) | PROGRAM(program-name) | TRANSACTION(transaction-name)] GROUP(group-name)

where:

ALL

Deletes all the entries in the group. Also deletes the group definition.

GROUP(group-name)

Name of the group from which to delete the resource(s).

MAPSET(mapset-name) |
PROGRAM(program-name) |
TRANSACTION
(transaction-name)

Resource (mapset, program, transaction) to delete. You can specify a generic resource name. If the resource specified is the last or group of last resources, the GROUP definition is also deleted.


Example: To delete the INVADD01 mapset that is in the CMP1INV group, type the following command on a blank transaction screen:

CEDA DELETE GROUP(CMP1INV) MAPSET(INVADD01)

DISPLAY Option

The DISPLAY option displays one or more resources.

Format:

CEDA DISPLAY ALL | [MAPSET(mapset-name) | PROGRAM(program-name) | TRANSACTION(transaction-name)] GROUP(group-name)

where:

ALL

Displays a list of all the resources along with their group names for the groups specified with the keyword GROUP.

GROUP(group-name)

If only group name is specified, a list of groups is displayed. You can specify a generic name.

MAPSET(mapset-name) |
PROGRAM(
program-name) |
TRANSACTION
(transaction-name)

Displays a list of all the resources (mapsets, programs, transactions) that match the specified name in the group specified with the keyword GROUP. You can specify a generic resource name.


Example: To display all resources in the CMP* group, type the following on a blank transaction screen:

CEDA DISPLAY GROUP(CMP*) ALL

INSTALL Option

The INSTALL option enables you to add or replace a resource definition into the region while the region is running.

Format:

CEDA INSTALL GROUP(group-name)
[MAPSET(
mapset-name)]
[PROGRAM(
program-name)
[TRANSACTION(
transaction-name)]

where:

GROUP(group-name)

Name of the group from which to dynamically add the resources to the executing region. You cannot use a generic name.

MAPSET(mapset-name)

PROGRAM(program-name)

TRANSACTION(transaction-name)

Name of the resource to dynamically add to the executing region. You can use a generic name. If omitted, all the resources from the group specified in the GROUP parameter are added.


Example: To install all the resources in the CMP1INV group, type the following command on a blank transaction screen:

CEDA INSTALL GROUP(CMP1INV)


CEDF - Execute Debug Facility

Use the CEDF transaction to access the Sun MTP Debug Facility or to select a source debugger. The Debug Facility is used for debugging EXEC CICS statements embedded in COBOL, C, and PL/I programs. CEDF provides a wide range of options for setting breakpoints, those locations where control is interrupted and passed to the Transaction Server for debugging purposes. CEDF allows debugging for single or multiple terminal sessions, as well as debugging for routed transactions.

For more information about the CEDF transaction, debugging, and breakpoint processing, refer to the Sun Mainframe Transaction Processing Software Developer's Guide.


CEMT - Set/Display Status

Use the CEMT transaction to perform system maintenance tasks, including:

To execute CEMT, enter the transaction identifier and its arguments in the upper left corner of the screen and press Enter.

Format:

CEMT INQ|SET|PERFORM arguments

where:

I[NQ]

Make inquiries. See INQ (I) Option.

S[ET]

Control the operating environment. See SET (S) Option.

P[ERFORM]

Perform a system activity. See PERFORM (P) Option.

arguments

The arguments vary with the option you are executing.


INQ (I) Option

The INQ option, which you can abbreviate as I, displays the current status of the specified tasks or queues.

Format:

CEMT I[NQ] [TASK ALL | (taskno)] |
[TRANID (
tranid)] |
[FACILITY (
facid)] |
[ACTIVE] |
[SUSPENDED] |
[TERM] |
[DEST] |
[CONN] |
[TDQUEUE | ALL] |
[PROG[RAM] (
prog-name) LIB[rary]] |
[TDQUEUE (
queue-id) | ALL] |
[TRANCLASS (
class-name) | ALL]

The following commands display status:

CEMT INQ TASK

All terminals and background processes currently logged on. Defaults to ALL.

CEMT INQ TASK ALL

All terminals and background processes currently logged on.

CEMT INQ TASK taskno

Only the task with the specified task number. Use the TASK ALL option to determine task numbers.

CEMT INQ TRANID tranid

Only the tasks executing the specified transaction identifier.

CEMT INQ FACILITY facid

Only the tasks with the specified facility identifier, which is a terminal identifier for terminal-initiated tasks and a transaction identifier for start- or trigger-initiated tasks.

CEMT INQ ACTIVE

All tasks currently active.

CEMT INQ SUSPENDED

All tasks currently suspended pending availability of a resource.

CEMT INQ TERM

Initiated tasks.

CEMT INQ DEST

All trigger-initiated tasks.

CEMT INQ CONN

All remote system connections.

CEMT INQ TDQUEUE queue-id

A specified transient data queue, where queue-id is a 4-character value that identifies the queue.

CEMT INQ TDQUEUE ALL

All transient data queues.

CEMT INQ PROG[RAM] prog-name LIB[RARY]

 

Name of the current shared library. If the program has a shared library, the transaction displays the name of the library, for example:

CEMT transaction terminated ShrLib = libc

Otherwise, the transaction displays the library name as:

NoSharedLibPrsnt

CEMT INQ TRANCLASS (class-name)|ALL

 

Displays the max active, current max active (number of transaction processors assigned to this class), number of messages or transactions received, the current queue depth, and the maximum queue depth. See FIGURE 4-5 for a sample display.


When you execute the CEMT INQ transaction for tasks, such as CEMT INQ TASK ALL, the User Status Table is displayed.

  FIGURE 2-13 CEMT INQ TASK ALL Display

Screen shot of the User Status Table, which is displayed when you execute the CEMT INQ TASK ALL transaction.[ D ]

The User Status Table contains the following fields:

Field

Description

TrmID

Indicates the terminal identifier associated with the task (transaction). If the field is blank, the transaction is not associated with a terminal.

Task#

Identifies the task number. Each task is assigned a unique sequential number when it enters the system.

TranID

Identifies the transaction.

FacID

Identifies the facility. This is the terminal identifier for terminal-initiated tasks, or the transaction identifier of the initiating transaction for asynchronously started tasks or triggered tasks.

Init

Indicates the initiation type. One of the following values is displayed:

E: Terminal

T: Start

D: Trigger (transient data queue)

C: Remote system connection

St

Indicates the current status of the task. One of the following values is displayed:

RQ: On the ready queue

WB: Waiting for an I/O buffer

WR: Waiting for a resource

VI: VSAM idle

ST: Executing status request

ID: Idle

EQ: On the event queue

IN: Connection to a remote system in service

OU: Connection to a remote system out of service

Request

Identifies the CICS command being executed.

File/Rsrc

Identifies the file or resource being requested.

RCD

Identifies the physical record number being requested.


When you execute the CEMT INQ transaction for transient data queues, such as CEMT INQ TDQUEUE ALL, the Destination Control Table information screen is displayed.

  FIGURE 2-14 CEMT INQ TDQUEUE ALL Display

Screen shot of the Destination Control Table Information screen, which is displayed when you execute the CEMT INQ TDQUEUE ALL transaction.[ D ]

The Destination Control Table Information screen contains the following fields:

Field

Description

Queue

Identifies the queue name.

Type

Indicates the queue type. One of the following values is displayed:

EXTRA: Extrapartition queue

INTRA: Intrapartition queue

REMOTE: Remote queue

Open

For extrapartition queues, indicates if the queue is open. Values are:

Y: The queue is open.

N: The queue is closed.

Enabled

For all types of queues, indicates if the queue is enabled. Values are:

Y: The queue is enabled.

N: The queue is disabled.

Trigger

Indicates one of the following:

Trigger level for intrapartition queues

Zero (0) for other queue types

TranId

Indicates one of the following:

Identifier of the transaction associated with an intrapartition queue

Blank for other queue types

Term

Indicates one of the following:

Name of the terminal associated with an intrapartition queue

Blank for other queue types


SET (S) Option

The SET option, abbreviated as S, enables you to manage aspects of a region. The parameters that follow the SET option determine the action taken.

Loading a New Copy of a Resource

To load a new copy of a program or mapset, submit the following transaction:

CEMT SET PROGRAM (resource-name) NEWCOPY

The next time the program or map is referenced, commands like LOAD, LINK, SEND MAP, and XCTL perform their functions on the new version.

The CEMT . . . NEWCOPY transaction is preferred over the CINI transaction for introducing new programs or mapsets.

When using CEMT . . . NEWCOPY to load a program, all programs are flushed. The next request for the program is loaded from the appropriate directory. Therefore, any program in the directory that has been updated since the region started or since the last CINI or CEMT transaction for a program was issued is read into memory the next time it is referenced.

The following example illustrates how CEMT behaves with programs:

1. The $KIXPROGS directory contains PROG1 version 1 and PROG2 version 1. When a user requests PROG1 and PROG2, they are loaded in the local memory of the transaction processor.

2. The administrator updates PROG2 to version 2.

3. If the administrator executes CEMT SET PROGRAM (PROG1) NEWCOPY, the transaction processors are restarted. This means all the programs are removed from the processor memory. The result is that even though the request for a new copy was for one program, the user will see all the programs as new copies, for example PROG1 version 1 and PROG2 version 2.

When loading a mapset, CEMT . . . NEWCOPY copies only the new mapset from the $KIXMAPS directory to either the $KIXSYS/_kix_reserved_maps directory or to the directory specified by the _KIX_RESERVED_MAPS environment variable. Refer to the Sun Mainframe Transaction Processing Software Configuration Guide for a description of $_KIX_RESERVED_MAPS.

The following example illustrates how CEMT behaves with mapsets:

1. The $KIXMAPS directory contains MAP1 version 1 and MAP2 version 2. When an application requests mapset MAP1, it is copied into the $KIXSYS/_kix_reserved_maps directory and loaded into shared memory.

2. The administrator updates MAP1 to create version 2.

3. If an administrator executes CEMT SET PROGRAM (MAP1) NEWCOPY, MAP1 version 1 is removed from shared memory and deleted from the $KIXSYS/_kix_reserved_maps directory. Then MAP1 version 2 is copied into the $KIXSYS/_kix_reserved_maps directory and loaded into shared memory.

Unlike CICS, the check for RESCOUNT is not made when issuing a CEMT . . . NEWCOPY for a program.

Exercise care when changing the version of a program in the production system. If one of the transaction processors is restarted because a program aborts (for example, trying to access memory outside the limits of the local process), the changed version of the program is loaded only for that transaction processor. This means that the new transaction processor will use the new version of the program, while other transaction processors will still have the old version of the program in process local memory.

Loading a Shared Library or Shared Object

To dyamically load a new copy of a shared library or shared object while a region is running, or to remove the designated program from processing, use the following transactions.

CEMT SET PROGRAM prog-name LIBRARY lib-name

Loads a new copy of the named shared library or shared object, up to 16 characters.

CEMT SET PROGRAM prog-name LIBRARY blankreset

Removes the designated program from shared library/object processing. The keyword blankreset sets the Program Processing Table (PPT) shared library field for the program to blanks.



Note - You must spell the keyword blankreset exactly as shown or the keyword is used as a new shared library/object name.



After you execute either CEMT transaction, you must execute a CINI transaction to initialize the new shared library/object and internal tables.

For more information about shared libraries and shared objects, refer to the Sun Mainframe Transaction Processing Software Developer's Guide.

Enabling or Disabling Programs and Transactions

To dynamically enable or disable a program or transaction, use the following transactions:

CEMT SET PROGRAM prog-name [DISABLED|ENABLED]

CEMT SET TRANSACTION tranid [DISABLED|ENABLED]

You can abbreviate DISABLED with a D and ENABLED with E.

When the CEMT SET TRANSACTION DISABLED command is used, existing transactions run to completion before being disabled.

Requesting a Transaction Dump

The following transaction allows you to specify whether a transaction dump should be done if the task executing the transaction terminates abnormally.

CEMT SET TRANSACTION tranid [TRANDUMP|NOTRANDUMP]

where:

TRANDUMP

A dump should be produced.

NOTRANDUMP

A dump should not be produced.




Note - This transaction is specific to Sun MTP.



Terminating Tasks

To terminate tasks, use either transaction:

CEMT SET TASK taskno PURGE

Purges the task with the specified task number (taskno). Use the CEMT INQ TASK ALL transaction to determine task numbers.

CEMT SET TASK ALL PURGE

Purges all tasks.

Managing Transient Data Queues

Manage transient data queues with these transactions, which enable you to:

All data queues are enabled at startup and may be disabled dynamically. Runtime modifications are not written to disk. Therefore, when the region shuts down, the queue status and trigger level return to their original status as defined in the DCT.

CEMT SET TDQUEUE (queue-id) [OPEN | CLOSED]

Opens or closes the specified queue. Applies only to extrapartition queues.
queue-id is a 4-character value that identifies the queue.

CEMT SET TDQUEUE (queue-id) [ENABLED | DISABLED]

Enables or disables the specified queue. Applies to all types of transient data queues. queue-id is a 4-character queue identifier.

Combinations of OPEN or CLOSED and DISABLED are not allowed.

Combinations of OPEN or CLOSED and ENABLED are allowed.

You cannot open or close a disabled queue.

You cannot disable an open queue.

Reading from, writing to, or deleting a disabled queue causes the transaction to abort and returns a disabled condition.

CEMT SET TDQUEUE (queue-id) [TRIGGERLEVEL (integer)]

Number of output requests to allow before a transaction is initiated. The level is any integer from 0 to 32767. Applies only to intrapartition queues. queue-id is a 4-character queue identifier.

You can issue the transactions with or without parentheses surrounding the variables for the queue ID and trigger level. For example:

CEMT SET TDQUEUE (queue-id) TRIGGERLEVEL (integer)

CEMT SET TDQUEUE queue-id TRIGGERLEVEL integer



Note - Do not specify a queue-id of ALL.



To execute a command again, you must clear the screen and retype the CEMT SET TDQUEUE transaction instead of pressing the Enter key again.

Controlling 3270 Devices

You can control 3270 devices with these CEMT SET TERMINAL transactions. The trmid variable is a 4-character terminal ID known to the application and defined in the 3270 Devices screen of the Terminal Control Table (TCT).



Note - You can use these transactions only if the SNA server is installed and the 3270 device is defined in the TCT.



CEMT SET TERMINAL trmid INSERVICE

Logs the terminal onto the region with the specified terminal ID.

CEMT SET TERMINAL trmid OUTSERVICE

Logs the specified terminal off the region.

Controlling Intersystem Connections

You can control intersystem connections with the following CEMT SET CONNECTION transactions. The sysid variable is a 4-character remote system ID known to the region and defined in the System Entries screen of the TCT.

CEMT SET CONNECTION sysid INSERVICE

Sets the connection to the specified remote system in service.

CEMT SET CONNECTION sysid OUTSERVICE

Sets the connection to the specified remote system as out of service. No ISC functions can use this connection.

Assigning Transaction Processors to Transaction Classes

You can dynamically change the maximum active transaction processors for a class. Parameters are validated for correctness and consistency before any action is taken. For example, changing MAXACTIVE to a value larger than the number of configured transaction processors is not permitted.

CEMT SET TRANCLASS class-name1 MAXACTIVE value [[USE] class-name2]

Changes the maximum active transaction processors for the specified class. The optional USE clause allows you to specify the class from which transaction processors are added or subtracted. If you do not specify the USE clause, transaction processors are added to or subtracted from the KIXDFLT class.

See Chapter 4 for information about setting up and using transaction classes.

Setting the System State

Set the system state with the following transactions:

CEMT SET SYSTEM NORMAL

Sets the system state to NORMAL.

CEMT SET SYSTEM BATCH

Sets the system state to BATCH.

CEMT SET SYSTEM QUIESCE

Sets the system to the QUIESCE state.

CEMT SET SYSTEM SHUT[DOWN]

Sets the system to the SHUTDOWN state in which executing transactions are allowed to complete.

CEMT SET SYSTEM SHUT[DOWN] IMM[EDIATELY]

Sets the system to a SHUTDOWN IMMEDIATE state in which executing transactions are not allowed to complete.

The following table illustrates the conditions and restrictions that are placed on the region for the various system states and for shutdown.

[ D ]
TABLE 2-2 System States

State

New Logons

Batch Programs

New Transactions

NORMAL

Allowed

Allowed

Allowed

BATCH

Not allowed 1

Allowed 2

Not allowed 1

QUIESCE

Not allowed 1

Not allowed

Not allowed 1

SHUT

Not allowed 1

Not allowed

Not allowed 3

SHUT IMM

Not allowed

Not allowed

Not allowed

1 A user with an Operator Class set to SYS can perform this action. Refer to the section on the Sign-on Table in the Sun Mainframe Transaction Processing Software Reference Guide.
2 Users cannot execute batch programs with the CBCH transaction if the system is in BATCH state.
3 Any user with the appropriate transaction security key can perform these system transactions: CEMT, CSMT, and CPLT.

Table showing the system states and the types of activities that can occur during each state.

PERFORM (P) Option

The PERFORM option, abbreviated as P, is used to:

Format:

CEMT P[ERFORM] SHUT[DOWN] [IMM[EDIATE]]
SECURITY REBUILD

where:

CEMT PERFORM SHUTDOWN

Sets the region to the SHUT state. No new activities are allowed. TABLE 2-2 shows the activities allowed when the region is in this state.

CEMT PERFORM SHUTDOWN IMMEDIATE

Shuts down the entire region immediately. Every user session and transaction is terminated. Transactions in process are rolled back and recovery processes are activated.

CEMT PERFORM SECURITY REBUILD

Clears the cache memory area where the results of access requests are stored.


CINI - Reinitialize Transaction Servers

The CINI transaction forces each transaction server in the system to terminate and restart as soon as it completes the currently executing transaction, clearing all programs out of local memory and all mapsets from shared memory and deleting all mapsets from the $KIXSYS/_kix_reserved_maps (or $_KIX_RESERVED_MAPS) directory. When you issue a CINI transaction, programs are loaded from $KIXPROGS and mapsets from $KIXMAPS, when requested by the user. A copy of the mapsets is also placed in the $KIXSYS/_kix_reserved_maps directory.

The CINI transaction has no arguments.


CRTE - Route Transactions

Transaction routing allows terminals connected on one system to run transactions in another system. Sun MTP uses the CRTE transaction to route transactions. See Transaction Routing for information about using the CRTE transaction.


CSMT - System Termination

Use the CSMT transaction to terminate a user's session or to shut down the region. Type the transaction identifier with its arguments in one of the following formats:

CSMT SHUT[,NO]

Terminates the user's session.

CSMT SHUT,YES

Shuts down the region for all users.



Note - For CSMT SHUT,YES to work correctly, do not include a space between the comma and YES.



When transaction security is in effect, the CSMT transaction should be secured to prevent users from accidentally shutting down the system while other users are signed on. If this transaction is secured, terminate a user session with the CSSF GOODNIGHT or CSSF LOGOFF commands. See CSSN/CSSF - Sign-On/Off.


CSPG - System Paging

Use the CSPG transaction to display multiple pages of data at a terminal using CICS BMS. The pages of data are created using either the SEND TEXT ACCUM or the SEND MAP ACCUM command. When all data has been created, a SEND PAGE command is issued. If there are multiple pages of data, the CSPG transaction is started to control the display of the data.

When CSPG starts, the first page of data is displayed. By entering a command in the first unprotected field on the screen or by using a PF key, you can page forward, page backward, display a specific page, or quit.

Command string format:

P/[+n | -n | n | P | N | L | C]

where:

P/

Indicates the command is starting.

  • n: Displays the page specified by n. If n is preceded by a + or -, the number is added to or subtracted from the current page.
  • P: Displays the previous page.
  • N: Displays the next page.
  • L: Displays the last page.
  • C: Displays the current page.

Before you can use PF keys to control paging, you must define them in the System Initialization Table (SIT). The following PF keys are defined by default:

PF3

Quit.

PF7

Displays the last page.

PF8

Displays the next page.



Sign-On/Sign-Off Transactions

There are several sign-on/sign-off transactions:

CESN

Signs on to the region with a user ID and password, and allows you to change your password.

CSSN

Signs on to the region with an operator name and password.

CSSF or CESF

Signs off, and optionally, terminates the client.

The CESN and CSSN transactions use the SNT to validate the user's ID and password. User programs can access the SNT fields with the EXEC CICS ASSIGN command.

CESN - Sign-On

Type CESN alone or with data. If you type CESN alone, the screen in FIGURE 2-15 is displayed.

Security issue: When external security management is enabled (KIXSEC=YES), you cannot use the CESN transaction without a password. See Chapter 9.

  FIGURE 2-15 CESN Signon Screen

Screen shot showing the Signon screen that displays when you type the CESN transaction.[ D ]

When you type, the Password and New Password values are not displayed. To change the password, type the new password in both New Password fields. The Userid, Password, and New Password values are one to eight characters in length. The password is case-sensitive. Refer to the Sun Mainframe Transaction Processing Software Reference Guide for information about setting the password type.



Note - If you use the CESN transaction from a terminal that is already signed on, the previous user is signed off immediately.



If you choose to enter all data with the CESN transaction identifier, use the format:

CESN USERID=userid,PS=password,[NEWPS=newpassword]

CSSN/CSSF - Sign-On/Off

Type CSSN alone or with a password. If you only type CSSN, the screen in FIGURE 2-16 is displayed.

Security issue: When external security management is enabled (KIXSEC=YES), you cannot use the CSSN transaction without a password. See Chapter 9 for more information.

  FIGURE 2-16 CSSN Signon Screen

Screen shot of Signon screen displayed when you type the CSSN transaction.[ D ]

The password is case-sensitive; it must match the entry in the SNT.

If you are unable to log in and are working on an X terminal, press Ctrl-C to terminate the client; PF3 is not active on the signon screen.

If you choose to enter all data with the CSSN transaction identifier, use the format:

CSSN NAME=operator-name,PS=password

To log off, type one of the following transactions:

CSSF or CESF

Signs off the user session.

CSSF GOODNIGHT or CSSF LOGOFF

Signs off the user session and terminates the client.


Customizing the CSSN/CESN Transaction

You can customize the supplied CSSN/CESN transaction. A sample COBOL program, CSSNCESN.cl2, is located in the $UNIKIX/src/trans directory.


procedure icon  To Customize a Transaction

1. Define the transaction in the Program Control Table (PCT).

Do not use a group name.

Refer to the Sun Mainframe Transaction Processing Software Reference Guide for more information about the PCT.

2. Copy the CSSNCESN.cl2 program from $UNIKIX/src/trans to your $KIXPROGS directory.

3. Modify and compile the program.

4. Restart the region.

Your transaction is executed instead of the standard one.



Note - After you modify a system transaction, it becomes part of your application and you are responsible for maintaining it. Sun Microsystems is not responsible for supporting the changed transaction(s).