═══ 1. CICS for OS/2 Operation ═══ ═══ 2. Version Notice ═══ First edition (March 1996) This edition applies to Version 3.0 of IBM CICS for OS/2, program number 5622-808, and to all subsequent versions, releases, and modifications until otherwise indicated in new editions. This book is based on the Operation book for CICS for OS/2 Version 2.0.1, SC33-0881-01. Changes from that edition are marked by vertical lines to the left of the changes. The CICS for OS/2 Version 2.0.1 edition remains applicable and current for users of CICS for OS/2 Version 2.0.1, and can still be ordered using the old order number SC33-0881-01. Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address given below. Reader's comments on this publication should be addressed to: IBM United Kingdom Laboratories, Information Development, Mail Point 095, Hursley Park, Winchester, Hampshire, England, SO21 2JN. When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. (c) Copyright International Business Machines Corporation 1989, 1995. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. ═══ 3. Notices ═══ The following paragraph does not apply to any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore this statement may not apply to you. References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of the intellectual property rights of IBM may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact Laboratory Counsel, MP151, IBM United Kingdom Laboratories, Hursley Park, Winchester, Hampshire, England SO21 2JN. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, New York 10594, U.S.A. ═══ 3.1. Trademarks and service marks ═══ The following terms, used in this publication, are trademarks or service marks of IBM Corporation in the United States or other countries or both: ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ BookManager │ CICS │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Common User Access │ CUA │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ IBM │ Library Reader │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Operating System/2 │ OS/2 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Personal System/2 │ Presentation Manager │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ PS/2 │ RACF │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ SAA │ Systems Application Architecture │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ VTAM │ │ └───────────────────────────────────────┴──────────────────────────────────────┘ The following terms, used in this publication, are trademarks of other companies as follows: Adobe Systems Inc. PostScript Apple Computer Inc. Apple, Macintosh Btrieve Technologies Inc. Btrieve Intel Intel Lotus Development Corporation Lotus, Lotus Notes Micro Focus Limited Micro Focus Microsoft Corporation Microsoft, Windows Novell, Inc. Novell ═══ 4. Preface ═══ ═══ 4.1. What this book is about ═══ The CICS for OS/2 Operation book is intended as an introduction to CICS for OS/2 and its facilities. This book:  Gives an overview of CICS for OS/2, from topic Overview.  Gets you started with the product, from topic Getting started.  Explains the user interface, from topic The user interface.  Describes the transactions supplied with CICS for OS/2, from topic Supplied transactions.  Provides a detailed description of how to use the CEMT transaction, from topic The CEMT transaction.  Introduces the internal file manager of CICS for OS/2 and its associated utilities, from topic The CICS for OS/2 internal File Manager and utilities.  Describes the concepts you need to understand to use the internal file manager of CICS for OS/2 and its associated utilities, from topic Fundamentals of the CICS for OS/2 internal file manager. ═══ 4.2. Who this book is for ═══ This book is intended for anyone using CICS for OS/2. ═══ 4.3. What you need to know to understand this book ═══ You require a reasonable knowledge of the OS/2 environment. ═══ 4.4. How to use this book ═══ This book introduces the CICS for OS/2 system, its interface, and its use. Read Overview, Getting started, and The user interface if you are unfamiliar with CICS for OS/2. Read Supplied transactions if you are familiar with the interface, but not with the CICS-supplied transactions. Read The CEMT transaction for details of how to use the CEMT transaction to control resources in the CICS for OS/2 system. Read Fundamentals of the CICS for OS/2 internal file manager and The CICS for OS/2 internal File Manager and utilities for details of the internal file manager and its utilities. Where appropriate, this book gives references to more detailed descriptions elsewhere in the CICS for OS/2 library. ═══ 4.5. Command syntax ═══ In this book the syntax of commands is shown in a standard way. This syntax, commonly known as railroad syntax, is described in Command syntax conventions. You interpret the syntax by following the arrows from left to right, and from top to bottom, along the main path line. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 1. Command syntax conventions │ ├─────────────────────────────┬────────────────────────────────────────────────┤ │ SYMBOL │ MEANING │ ├─────────────────────────────┼────────────────────────────────────────────────┤ │ │ Required items appear on the main path line. │ │ >──A──B───────────────────> │ │ ├─────────────────────────────┼────────────────────────────────────────────────┤ │ │ If there is more than one required item to │ │ >──.-A-.──────────────────> │ choose from, the items are stacked vertically. │ │ |-B-| │ This is a set of alternatives-one of which you │ │ '-C-' │ MUST specify. │ ├─────────────────────────────┼────────────────────────────────────────────────┤ │ │ Optional items appear below the main path │ │ >──.───.──.───.───────────> │ line. │ │ '-A-' '-B-' │ │ ├─────────────────────────────┼────────────────────────────────────────────────┤ │ │ If there is more than one optional item to │ │ >──.───.──────────────────> │ choose from, the items are stacked vertically │ │ │-A-│ │ below the main path line. This is a set of │ │ │-B-│ │ alternatives-one of which you may specify. │ │ '-C-' │ │ ├─────────────────────────────┼────────────────────────────────────────────────┤ │ │ If one item in a set of alternatives is the │ │ .-A-. │ default, this item appears above the main path │ │ >──┬───┬──────────────────> │ line and all other items are stacked verti- │ │ │-B-│ │ cally below the line. │ │ '-C-' │ │ ├─────────────────────────────┼────────────────────────────────────────────────┤ │ │ An arrow returning to the left above items on │ │ <──────────< │ the main path line means that the items can be │ │ >────A──.───.─────────────> │ repeated. Such items may be either required │ │ '-B-' │ or optional. │ ├─────────────────────────────┼────────────────────────────────────────────────┤ │ │ An arrow returning to the left above a set of │ │ <─────< │ items means that more than one item can be │ │ >───.───.─────────────────> │ selected or that a single item can be │ │ │-A-│ │ repeated. │ │ │-B-│ │ │ │ '-C-' │ NOTE: For CICS unless otherwise stated, this │ │ │ representation means only that more │ │ │ than one item can be selected. │ ├─────────────────────────────┼────────────────────────────────────────────────┤ │ │ Use with the named section in place of its │ │ >>──| Name |─────────────>< │ name. │ │ │ │ │ NAME: │ │ │ |──A──.───.───────────────| │ │ │ '-B-' │ │ ├─────────────────────────────┼────────────────────────────────────────────────┤ │ Punctuation and uppercase │ Code exactly as shown. │ │ characters │ │ ├─────────────────────────────┼────────────────────────────────────────────────┤ │ Lowercase characters │ Code your own text, as appropriate. │ │ appearing like this │ │ └─────────────────────────────┴────────────────────────────────────────────────┘ For example, with FILE(name) you must specify FILE and () unchanged, but are free to specify any valid text string for the name of your file. ═══ 4.6. Notes on terminology ═══ There is a Glossary. CICS for OS/2 supports the use of both the C and C++ programming languages. For simplicity, `C' is used to refer to both the C and C++ languages throughout this book. ═══ 4.7. Publications ═══ ═══ 4.7.1. CICS for OS/2 publications ═══ IBM Transaction Server for OS/2 Warp Up and Running!, GC33-1674 This book guides you through the steps necessary to install a simple Transaction Server production environment with a CICS for OS/2 server and a CICS Client for OS/2 or a CICS Client for Windows connected via TCP/IP or NetBIOS. CICS for OS/2 Installation, GC33-1580 This book gives detailed information about how to install CICS for OS/2. It is intended for experienced users of the product, for example those migrating from a previous release. CICS for OS/2 Customization, SC33-1581 This book explains how to customize the CICS for OS/2 environment, and how to use the CEDA transaction and batch facilities to define resources. The other subjects covered include CICS for OS/2 security, software migration, and how to build user exits. CICS for OS/2 Operation, SC33-1582 This book provides an introduction to how to use CICS for OS/2. It gives an overview of CICS for OS/2; tells you how to get started; explains the user interface; and describes the commands and transactions supplied with CICS for OS/2. This book also describes the CICS for OS/2 File Manager. CICS for OS/2 Reference Summary, SX33-6100 This is a quick-reference booklet summarizing the CICS for OS/2 directory structure, supplied transactions and commands, environment variables, EXEC CICS commands, and other useful information. CICS for OS/2 Intercommunication, SC33-1583 This book tells you how to implement intersystem communication between two CICS for OS/2 systems, or between a CICS for OS/2 system and any other CICS product. For communication between two CICS for OS/2 systems, this book is all that is needed. For communication between a CICS for OS/2 system and a different CICS product, this book explains the CICS for OS/2 side of the communication link. There are corresponding books for other CICS products that describe the other side of the link. CICS for OS/2 Problem Determination, SC33-1584 This book provides step-by-step guidance for problem determination, explains how to contact your support organization, and lists the trace point information. CICS for OS/2 Performance, SC33-1747 This book describes how to use CICS for OS/2 Performance Analyser to monitor the usage of transactions and resources in a CICS for OS/2 system. CICS for OS/2 Application Programming, SC33-1585 This book describes the CICS command-level application programming interface, and contains guidance and reference information needed to prepare applications in the supported programming languages. The book also explains the differences between using CICS on a mainframe and on a workstation. CICS for OS/2 Messages and Codes, SC33-1586 This book lists the error messages and codes that can be generated by CICS for OS/2. ═══ 4.7.2. IBM CICS Clients publications ═══ IBM CICS Clients Administration, SC33-1436 This book describes the administration of the IBM CICS Clients:  CICS Client for DOS  CICS Client for OS/2  CICS Client for Windows  CICS Client for Macintosh It introduces the IBM CICS Clients and summarizes the benefits of using them. It describes how to install CICS clients and discusses the various ways in which CICS clients can be connected to CICS servers. It includes problem determination information and discusses migration from using CICS for OS/2 Distributed Feature clients to using IBM CICS Clients. IBM CICS Clients Gateways, SC33-1748 This book describes how to use the CICS gateway for Lotus Notes and the CICS Internet gateway. Their installation is covered in the IBM CICS Clients Administration book. IBM CICS Clients Messages and Codes, SC33-1458 This book lists the error messages and codes that can be generated by IBM CICS Clients and CICS gateway for Lotus Notes. ═══ 4.7.3. Other CICS publications ═══ Related books from other CICS libraries include: CICS Application Programming Primer (VS COBOL II), SC33-0674 CICS Family: API Structure, SC33-1007 CICS Family: Interproduct Communication, SC33-0824 CICS Family: Client/Server Programming, SC33-1435 ═══ 4.7.4. Hardcopy documentation ═══ For details of printing PostScript versions of CICS for OS/2 publications, or ordering printed copies from IBM, see CICS for OS/2 Operation book. ═══ 4.7.5. Online documentation ═══ The CICS for OS/2 publications are supplied in the following online documentation formats:  IBM Information Presentation Facility (IPF), in the product diskette and CD-ROM packages  IBM BookManager, in the product CD-ROM package only. For details of how to use CICS for OS/2 online documentation, see CICS for OS/2 Operation book. ═══ 5. Overview ═══ This topic  Introduces the CICS for OS/2 Version 3.0 system  Explains how the CICS for OS/2 Version 3.0 system is used  Summarizes the differences between CICS for OS/2 and mainframe CICS  Introduces the features and benefits of CICS for OS/2 Version 3.0. ═══ 5.1. What is CICS for OS/2? ═══ CICS for OS/2 Version 3.0 is a member of the CICS family of products, and makes CICS transaction processing available on a workstation running Operating System/2 (OS/2). This means that end users can run workstation-based CICS for OS/2 applications as well as applications on another connected CICS system. As well as supporting up to 40 locally-attached terminals, CICS for OS/2 Version 3.0 can also act as a CICS server to clients on a local area network (LAN). The recommended clients, which can run under OS/2, DOS, Microsoft Windows Version 3.1, or on the Apple Macintosh, are available with the separately purchasable IBM CICS Clients product. The Distributed Feature clients shipped with previous versions of CICS for OS/2 are also supported. CICS for OS/2 applications can be designed to use Presentation Manager to give familiar and consistent panel layouts and user interaction techniques. These are defined by the Common User Access (CUA) rules-a part of the Systems Application Architecture (SAA). With CICS for OS/2, workstation programmers have full facilities to develop applications using a major subset of the mainframe CICS application programming interface. They may use any supported C, C++, COBOL, or PL/I language compiler with source-level debugging and the CICS execution diagnostic facility (EDF). Existing mainframe CICS applications can be ported to the workstations with a minimum of modification. ═══ 5.2. How do you use CICS for OS/2? ═══ The use of CICS for OS/2 involves four distinct phases: Installation This consists of transferring CICS for OS/2 from the supplied media onto your workstation or server, from where you can then distribute CICS for OS/2 to other workstations in the LAN. See the CICS for OS/2 Installation book for details. Customization You can customize and configure the system according to requirements. See the CICS for OS/2 Customization book for details. Application development If you are a CICS programmer, you can migrate existing mainframe CICS applications to CICS for OS/2. (Or migrate applications from previous CICS for OS/2 releases.) You can also develop and test new applications for end-users. See the CICS for OS/2 Application Programming book for details. End-user activity As an end-user you can run CICS for OS/2 applications. As with mainframe CICS, when running applications CICS for OS/2 is largely hidden from you. These four phases can take place on one or several workstations, according to the practice in your organization. You can move CICS for OS/2 and application files between workstations by diskette, across a LAN, or via host transfer, whichever is appropriate, subject to license. CICS for OS/2 provides online help. ═══ 5.3. How does CICS for OS/2 differ from mainframe CICS? ═══ There are a few differences between CICS for OS/2 and mainframe CICS. These arise mainly from the characteristics of the different hardware on which they run. CICS for OS/2 applications can be developed on a mainframe with:  DOS/VS COBOL Compiler (5746-CB1)  OS/VS COBOL Compiler (5740-CB1)  VS COBOL II Compiler (5668-958)  C/370 Compiler (5688-040)  C/370 Library (5688-039). or on a workstation with:  IBM VisualAge for C++ for OS/2  IBM VisualAge for COBOL for OS/2  Micro Focus Object COBOL Version 3.3 for 32-Bit OS/2  IBM PL/I for OS/2  IBM C Set++ Applications can contain EXEC CICS commands, but not CICS macro level requests. Most mainframe CICS command-level COBOL programs can be translated and compiled for use on the workstation with no modifications. However, a few EXEC CICS commands are not supported or have fewer options, and some conditions cannot be raised on the workstation. CICS for OS/2 supports a minimum level of basic mapping support (BMS) (this is defined in the CICS for OS/2 Application Programming book) except for a small number of BMS macro operands. CICS for OS/2 of course, also provides interfaces to workstation programs. ═══ 5.4. What facilities are provided with CICS for OS/2? ═══ ═══ 5.4.1. CICS for OS/2 allows system programmers to: ═══  Define and maintain resources in control tables  Establish a communication link with other members of the CICS family  Define client-server interfaces  Enable Programmable Network Access (PNA) interfaces  Gain access to online help  Resolve problems concerning the installed system. ═══ 5.4.2. CICS for OS/2 provides facilities for CICS application programmers to: ═══  Translate and compile source, link-edit the compiled code, and translate screen maps into a form suitable for CICS for OS/2  Debug application programs using source-level debug facilities  Change the resource control tables as necessary  Gain access to online help  Write non-CICS programs that can call CICS programs running on the local CICS for OS/2 server, or on a remote CICS system  Write non-CICS programs to emulate CICS terminals and to provide graphical user interfaces to CICS transactions (the External Presentation Interface)  Use an alternative file manager (such as FileShare) by writing to the External File Manager interface provided. See the CICS for OS/2 Customization book for details. ═══ 5.4.3. CICS for OS/2 allows end users to: ═══  Manage the resources of the CICS for OS/2 system  Run CICS for OS/2 applications  Gain access to online help. ═══ 6. Getting started ═══ This topic explains how to  Start and stop a CICS for OS/2 system  Use IBM CICS Clients  Start a transaction from outside CICS for OS/2.  Attach and detach a Programmable Network Access (PNA) attached terminal to and from CICS for OS/2 Before you can use the information in this topic, the CICS for OS/2 programs must first have been installed on the workstations that you intend to use. For more information about this, please refer to the CICS for OS/2 Installation book. If you are using IBM CICS Clients, refer also to the IBM CICS Clients Administration book. If you are using the Distributed Feature clients supplied with previous versions of CICS for OS/2, refer to the Operation book appropriate to that version. ═══ 6.1. The CICS folder ═══ The CICS for OS/2 folder (see The CICS for OS/2 folder) contains objects that allow you to run a number of CICS for OS/2 functions, including starting and stopping the system. The objects contained in the folder depend on the options you selected at installation time. The CICS for OS/2 folder The CICS for OS/2 folder can contain the following objects: Object Purpose CICSENV.CMD Places the CICSENV.CMD file in the OS/2 system editor to allow you to change the CICS for OS/2 environment variables. CICS for OS/2 Manuals Opens a folder containing icons for CICS for OS/2 online books. Installation Utility Starts the installation and maintenance program. License Use Runtime - Client Opens a folder containing the utilities required to enrol the CICS for OS/2 users and licenses. For detailed information see the CICS for OS/2 Installation RAS Opens a folder containing problem determination utilities. For more information see the CICS for OS/2 Problem Determination book. README.TXT Opens the README file containing important information about CICS for OS/2, which may not be in other product documentation. You should read this information before using the system for the first time. Start CICS C:\CICS300 Starts the CICS for OS/2 system (see Starting a CICS for OS/2 system). Start Terminal Starts an additional CICS terminal Start Trace Starts writing CICS for OS/2 trace points to the auxiliary trace file in "append" mode. For more information see the CICS for OS/2 Problem Determination book. Stop CICS Starts a normal shutdown of the CICS for OS/2 system (see Normal shutdown). Stop CICS Immediate Starts an immediate shutdown of the CICS for OS/2 system (see Immediate shutdown). Stop Trace Stops writing CICS for OS/2 trace points to the auxiliary trace file. ═══ 6.2. Starting a CICS for OS/2 system ═══ You can start CICS for OS/2 from a CICS for OS/2 icon, or by entering the START CICSRUN command at the command prompt. ═══ 6.2.1. Starting from a CICS for OS/2 icon ═══ CICS for OS/2 can be started from the CICS for OS/2 folder at any time, as follows:. 1. Double-click on the Start CICS icon. A Start CICS window appears, containing several startup messages. This is followed almost immediately by an IBM logo panel. Although this panel has the option to click on an OK button, loading continues anyway after a few seconds. Note: At this point, if you have not previously started CICS for OS/2 and enrolled your CICS for OS/2 licenses and users, you will see the Licensing Information Panel appear, as shown in Licensing Information Panel. You cannot continue with the startup process until you have completed the enrollment. For details of how to do this, see the CICS for OS/2 Installation Licensing Information Panel Loading of CICS for OS/2 proceeds and messages are displayed in the Message Log window to indicate progress, as shown in Startup Messages in the Message Log. See Reading CICS for OS/2 messagesfor information about CICS for OS/2 messages. Startup Messages in the Message Log Another window titled CICS for OS/2 Terminal V123 appears on top of the Message Log window, and displays the IBM logo and copyright, as shown in CICS for OS/2 Logo Panel. CICS for OS/2 Logo Panel 2. Press the right-hand Ctrl key (in CICS for OS/2 this acts as the Enter key)(**). The signon panel is displayed in the Terminal V123 window. 3. Unless instructed otherwise by your systems administrator, sign on using the signon and password supplied with the system: Sign-on name ..........: SYSAD Password ..............: SYSAD then press the Enter key. A message is displayed to indicate that signon has been completed successfully. 4. Clear this message by pressing the Esc key. You may now enter any of the transactions listed in Supplied transactions. ═══ 6.2.2. Starting CICS for OS/2 with the CICSRUN command ═══ An alternative way of starting CICS for OS/2 is by entering the START CICSRUN command at a command prompt. 1. If necessary, change first to the correct subdirectory of your high-level directory, as in the following example: cd \CICS300\RUNTIME Normally the PATH statement in your CONFIG.SYS file is updated during the installation process so that this step is not necessary. If in doubt, contact your system administrator for details of the installation in your organization. 2. At the command prompt, enter START CICSRUN, with or without any of the CICSRUN parameters listed in the next section. After entering this command, the sequence of events is the same as for starting from a CICS for OS/2 icon. Note: When starting a CICS system for the first time from the command prompt, you must include the /C (cold start) parameter. You can simplify steps 1 and 2 by writing a command file that changes the directory and then runs CICSRUN. ═══ 6.2.3. Adding CICSRUN parameters ═══ You can add parameters when you enter CICSRUN on the command line. For example, you can:  Select the cold start parameter  Turn on the trace file and debugging facility. You may enter parameters in any order, separated by a slash (/). Trailing spaces are required after parameters, but are not allowed between a separator and a parameter. Any messages produced during the validation of CICSRUN parameters are written to the message log. CICSRUN parameters ┌─/W─┐ >>──CICSRUN──┼────┼──┬────┬──┬───────┬─────────────────────────────────────────> ├─/E─┤ └─/N─┘ └─/Q /Q─┘ └─/C─┘ >──┬────┬──┬─────────────────┬──┬────┬──┬───────┬──────────────────────────────> └─/T─┘ └─/D───parameters─┘ └─/P─┘ └─/P-PA─┘ ┌─/V-CICSWRK─┐ >──┼────────────┼──┬────────────┬─────────────────────────────────────────────>< └─/V-envar───┘ └─/J-jobname─┘ ═══ 6.2.3.1. Warm, cold, and emergency start parameters ═══ /W Warm start. This is the default. All transient data and temporary storage queues are retained. Any dump file, and the message log are also retained. /E The parameter /E (emergency) has the same effect as a warm start. Note that the use of /W is recommended, for consistency. /C Cold start. This resets both recoverable and unrecoverable temporary storage. All transient data and temporary storage queues are deleted, and any dump file is also deleted. The message log is cleared. ═══ 6.2.3.2. Minimized and quick start parameters ═══ /N Minimized start. The global task is minimized, but the workstation has no terminal windows. A minimized startup is typically used for a workstation that is being used only as a CICS server, for external transaction initiation (ETI), or only for the use of PNA-attached terminals (or a combination of these.) For a description of ETI, refer to the CICS for OS/2 Application Programming book and see Starting CICS for OS/2 transactions from outside CICS. Because the workstation of a CICS for OS/2 system started in this way has no terminal windows, it must be shut down from outside CICS for OS/2. One method is to use the supplied sample program FAAPMPSM (with TRANSID=CQIT), as described in Starting CICS for OS/2 transactions from outside CICS. An alternative method would be to use the Close option in the Message Log window. You can also use FAAPMPSM (with TRANSID=CESN) to open a terminal window to a system that has previously been started with the /N parameter. /Q Quick start. You must enter this twice (that is, enter /Q /Q), because the OS/2 command processor interprets the first /Q as one of its own parameters. Quick start gives system startup without the need for any operator intervention. It is necessary for unattended systems that are started automatically. Only severe errors stop initialization (errors are logged in the file CICSMSG.LOG). All facilities, such as 3151, PNA-attached, client, and workstation window sessions, are started. ═══ 6.2.3.3. Trace and debug parameters ═══ /T Trace. Sets the trace file running in overwrite mode. This parameter is used to trace events that occur before you could run the CETR transaction. /D Debug facility. With additional parameters, this calls up a choice of source-level debug facilities. See the CICS for OS/2 Application Programming book for details of additional parameters. /P Performance monitoring option to invoke the SPM/2 monitor. See the CICS for OS/2 Problem Determination book for more information. /P-PA Performance monitoring option to enable the Performance Analyser feature. See the CICS for OS/2 Performance book for more information. ═══ 6.2.3.4. Library path parameter ═══ /V-envar Sets the path from which CICS for OS/2 gets its user application programs. It is entered in the form /V-envar where envar is an environment variable. The default value is CICSWRK, but if the variable has not been set by running CICSENV.CMD, then the default is the current directory. See the CICS for OS/2 Customization book for more information about setting environment variables. ═══ 6.2.3.5. Jobname parameter ═══ /J-jobname Enables you to change the 8-character jobname for the system from the default of `CICSRUN' The jobname can be viewed by including the JOBNAME option on the EXEC CICS INQUIRE SYSTEM command. ═══ 6.2.4. Starting CICS for OS/2 remotely ═══ You can also start a CICS for OS/2 system from a remote workstation or host terminal communicating over an APPC link. This is achieved by creating a distributed transaction processing (DTP) application, which you can then invoke from the remote CICS system. Create the front-end of the DTP application at the remote system, using a Transaction Code of CRUN. A set of sample CICS programs are supplied for this purpose: FAADCRUN.CCP - for Cobol FAACCRUN.CCS - for C FAADPRUN.PLI - for PL/I The back-end of the DTP application, located at the CICS for OS/2 server, is a native APPC program FAAUTPST.EXE. Use the Transaction Program Definition panel of Communications Server to define the inbound request to it as follows: 1. Set Transaction program (TP) name to CRUN. 2. Set OS/2 program path and file name to C:\CICS300\RUNTIME\FAAUTPST.EXE. Note: This assumes that you used the default drive and directory when installing CICS for OS/2. If you did not, enter the actual pathname used. 3. Leave the Optional values fields blank. 4. Click on the Continue button to move to the Additional TP Parameters panel. 5. Within Presentation type select VIO-windowable. 6. Within Operation type select Non-queued, Attach Manager started. To start CICS for OS/2 at the remote system, enter: CRUN [optional parameters] where the optional parameters are any of those that may be supplied to the CICSRUN command file, as described in Starting CICS for OS/2 with the CICSRUN command. The back-end program FAAUTPST.EXE returns the following data stream: CRUN Rc DosRc where: Rc is a 1 byte binary return codes, with possible values: 0 CICS for OS/2 was started successfully 1 CICS for OS/2 was already running 2 DosQuerySysInfo returned an error 3 DosSearchPath returned an error searching PATH for CMD.EXE 4 DosStartSession returned an error attempting to start CICSRUN.CMD DosRc is a 2 byte binary return code containing the return code from OS/2 if any of the operating system calls returned an error. This field is in Intel binary format, with the least significant byte first. Note: The directory containing CICSRUN.CMD must be defined in the PATH statement of CONFIG.SYS at the CICS for OS/2 server for remote start to be successful. This will be the case if default values were used during installation. ═══ 6.3. Starting CICS for OS/2 transactions from outside CICS ═══ A CICS for OS/2 facility called external transaction initiation (ETI) allows you to start CICS transactions from outside CICS for OS/2. This means you can create an icon in a OS/2 folder so that you can start a transaction simply by clicking on the icon. This is a useful way of quickly running transactions that you use frequently. A sample ETI program, FAAPMPSM, is supplied with CICS for OS/2. This program can be used to run CICS for OS/2 transactions from a program object. The following example shows entries in the settings notebook of a program object. This example would produce an icon to run the CEDA transaction from user ID CHARLES on terminal V123: Path and File Name For example: C:\CICS300\RUNTIME\FAAPMPSM.EXE Parameters USAGE=3270 USERID=CHARLES PASSWORD=* TERMID=V123 TRANSID=CEDA Title A title of your choice, for example, Resource Definition, CEDA. If you set the USERID or PASSWORD parameter to asterisk (*), a dialog box prompting you for the missing parameters is displayed. For further information on ETI and FAAPMPSM, see the CICS for OS/2 Application Programming book. ═══ 6.4. Shutting down the system ═══ The options for shutting down CICS for OS/2 are either to close down the system completely, or to disconnect an individual terminal. Attention: You must shut down CICS for OS/2 completely before shutting down OS/2. If you shut down OS/2 with CICS for OS/2 still active, you may lose data. ═══ 6.4.1. Shutting down completely ═══ You can use either the CEMT or the CQIT transaction to completely shutdown the CICS for OS/2 system, and in both cases you can request either a normal or an immediate shutdown. Enter a CQIT request as follows, or see The CEMT transaction for details of how to use CEMT. ═══ 6.4.1.1. Normal shutdown ═══ Enter CQIT without parameters. Messages are displayed, and you are returned to the OS/2 Desktop, if none of the messages are of type W (warning), E (error) or S (severe error). If there are any messages of these types, the message log window tells you and prompts you to press Enter. The message log window is displayed with all the messages for the task that gave the error. (This does not occur if the /Q /Q parameters were specified at startup.) ═══ 6.4.1.2. Immediate shutdown ═══ Enter CQIT IMMEDIATE. All active transactions end abnormally with abend ATCH. CICS for OS/2 shuts down, and control is returned to the operating system. As an alternative to CQIT, you can use the Close option on the Message Log window. The first time you select the Close option, then confirm the action, the system shuts down normally. Any subsequent selection of the Close option will cause an immediate shutdown. ═══ 6.4.2. Disconnecting a terminal ═══ The recommended method of disconnecting a terminal is to use the CESF transaction with the LOGOFF parameter. You can also use the EXIT transaction to shut down a terminal window, leaving CICS for OS/2 running. ═══ 6.4.3. Reconnecting a terminal ═══ When you have used the EXIT transaction to shut down a terminal window, and later wish to create a new window, you can use the supplied sample program FAAPMPSM, as described in Starting CICS for OS/2 transactions from outside CICS below. In this case you should set the value of the TRANSID parameter to CESN. ═══ 6.5. Using IBM CICS Clients ═══ You can use IBM CICS Clients for DOS, OS/2, Windows, and Macintosh with CICS for OS/2. The use of these clients is described in the IBM CICS Clients Administration book. The clients can communicate with the CICS for OS/2 server through:  Terminal emulation  The external call interface (ECI)  The external presentation interface (EPI). The ECI and EPI are described in the CICS Family: Client/Server Programming book. If you wish to use the Distributed Feature clients supplied with previous versions of CICS for OS/2, see the Operation book appropriate to the relevant version of the product. ═══ 6.6. Programmable Network Access (PNA) Support ═══ A CICS for OS/2 system supports the attachment of up to 4 3151 Model 5, or 6 ASCII terminals via the serial COMx ports. In addition, you can use Programmable Network Access (PNA) support to attach further ASCII terminals (up to 40 for a Model 95 PS/2). The actual number of terminals that can be attached in these ways depends on the hardware adapters installed. The terminals can communicate directly with CICS for OS/2, or with any other CICS system (for example, on a mainframe) to which a link is provided. A PNA-connected terminal can be attached to, or be detached from, CICS for OS/2 as often as desired. You have the ability to switch freely between CICS for OS/2 and other applications. ═══ 6.6.1. Starting PNA ═══ The system administrator or operator of the CICS for OS/2 server system starts PNA from the \PNA directory. For example: PNASTART CICSOS2 The parameter for PNASTART is the name chosen for the PNA application and is also the name of the PNA configuration file (CICSOS2.NET in this example). See the CICS for OS/2 Installation book for details of how PNA is installed, and how the configuration file is generated. When PNA is started, a PNA Operator Console session is started on the CICS for OS/2 workstation and a panel like Terminal Selection Panel is displayed at the attached ASCII terminals (the appearance of this panel is determined when PNA is installed and configured). Terminal Selection Panel ┌──────────────────────────────────────────────────────────────────────────────────┐ │ │ │ == IBM SYSTEM ========= Terminal Selection Panel ================== PORT 01 == │ │ │ │ PPPPPPPPPP NN NN AAAAA │ │ PP PP NNN NN AA AA │ │ PP PP NNNN NN AA AA │ │ PP PP NN NN NN AA AA │ │ PP PP NN NN NN AA AA │ │ PPPPPPPPPP NN NN NN AAAAAAAAAAA │ │ PP NN NNNN AA AA │ │ PP NN NNN AA AA │ │ PP NN NN AA AA │ │ PP NN N AA AA │ │ │ │ │ │ 0- MINITEL 1B/10 1- DEC V100 2- IBM PC/FTTERM COLOR │ │ 3- IBM PC/FTTERM MONO 4- IBM 3101 5- IBM 3151 Model 2 │ │ 6- IBM 3161/63 7- IBM 3162 8- IBM 3164 │ │ 9- IBM 3151 Model 5 │ │ │ │ Type the number that matches your terminal type, │ │ and press the CR key (carriage return). │ │ (To modify, use the BACKSPACE key.) │ │ │ │ ===> │ │ │ │ │ └──────────────────────────────────────────────────────────────────────────────────┘ The Operator Console is described in the PNA Service Coordinator's Guide, SH33-7048. ═══ 6.6.2. Enabling the CICS for OS/2-PNA interface ═══ After PNA has been started, the CICS for OS/2-PNA interface must be enabled (that is, CICS for OS/2 must be connected to PNA). This can be done:  Automatically at system initialization, if the CEDA transaction is used to set the SIT Load PNA support field to Y  After CICS has come up, by means of the CEPN transaction (see Connecting and disconnecting from PNA-CEPN transaction). ═══ 6.6.3. Attaching a PNA-connected terminal to CICS for OS/2 ═══ Before you attach a terminal, PNA must be started and the CICS for OS/2-PNA interface enabled. To attach a PNA-connected terminal to CICS for OS/2, you must specify your terminal type. In the example shown in Terminal Selection Panel, you enter the number that matches your terminal type in the Terminal Selection Panel. (The procedure depends on how this panel has been customized during PNA installation.) This requests CICS for OS/2 to start a terminal session. On receipt of the request, CICS for OS/2 autoinstalls the terminal. If defined, a user exit is called to set attributes for the terminal (see the CICS for OS/2 Customization book for details) and this deternines the appearance of the screen displayed. For example, the user exit may specify CESN as the initial transaction, in which case the CESN panel is displayed when the terminal has been attached. ═══ 6.6.4. Detaching a PNA-connected terminal from CICS for OS/2 ═══ A terminal can be detached from CICS for OS/2 in any the following ways: 1. Enter CESF LOGOFF to sign off the user from CICS for OS/2 and disconnect the terminal from CICS for OS/2. This is the recommended method. 2. If the session terminates abnormally (for example, there is a power failure, or PNA abend) and a transaction subsequently attempts to use terminal control, the transaction terminates abnormally, with abend ATNI. ═══ 7. The user interface ═══ This topic  Shows the basic panel layout  Explains how to select CICS for OS/2 panels  Explains CICS for OS/2 actions and the action bar  Indicates the meaning of different message types  Tells you how to get help  Describes the use of the mouse and the keyboard  Gives the supplied keyboard configuration. ═══ 7.1. Layout of CICS for OS/2 panels ═══ CICS for OS/2 panels conform to IBM Common User Access (CUA) standards, as specified in the Common User Access Panel Design and User Interaction book. The basic structure of a CICS for OS/2 panel is shown in The basic CICS for OS/2 panel. The basic CICS for OS/2 panel ┌──────────────────────────────────────────────────────────────────────────────┐ │ │ │ ───────────────────────────action bar────────────────────────────────── │ │ │ │ Panel identifier ─────────title line───────── │ │ │ │ ┌──────────────────────────panel body──────────────────────────────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ ──────────────────────function keys──────────────────────────────────── │ └──────────────────────────────────────────────────────────────────────────────┘ Action bar This shows the actions you can perform from the current screen: see What the CICS for OS/2 actions do. The Help and Exit actions are always available. They correspond to the function key settings supplied by CICS for OS/2 for F1 and F3: see Function keys. Panel identifier Each panel displays its own identification in the form FAAxxxx. Title line This shows the panel title. Panel body The panel body contains the field descriptions of a CICS for OS/2 display. If a field has a default value, that value is shown. If you blank out a field that has a default value, the default value is still used when you press the Enter key. Function keys This shows the function keys that you can use on the current panel. See Function keys. ═══ 7.2. Using panels ═══ The transactions supplied with CICS for OS/2 use different levels of panels. This section describes the content of the panels and how to move between them, using the panels from the CEDA transaction as an example. CEDA has three levels of panel: table menu, entry summary, and entry detail. Note: Authorization is necessary to use the CEDA transaction. The supplied user ID SYSAD gives this authorization. ═══ 7.2.1. Menu panels ═══ After entering CEDA you will see the menu panel shown in Example of a menu panel. Process Exit Help FAAEDA1 Resource Definition Online Type / against a Table Name. Then select one of the actions shown. / Table Description _ CVT Data Conversion Table _ DCT Destination Control Table _ FCT File Control Table _ PCT Program Control Table _ PPT Processing Program Table _ SIT System Initialization Table _ SNT Signon Table _ TCS Connection and Session Table _ TCT Terminal Control Table _ TST Temporary Storage Table _ WSU Workstation Set Up _ GRP Group Processing Enter F1=Help F3=Exit F10=Actions F12=Cancel Example of a menu panel At the top of the panel is the action bar. To move between actions, first press F10, then tab to the required action. You will find more detail on using the action bar, and what the actions do, in The CICS for OS/2 action bar. Beneath the action bar are the panel identifier and title line. The next line reminds you how to make your selection and perform an action, and is followed by the list of entries from which you can select. To select entries type a slash (/) in the column next to the entries you want, and then press Enter. For the purpose of this example, select DCT (Destination Control Table). ═══ 7.2.2. Summary panels ═══ A summary panel is displayed when you select a table from the CEDA menu. Example of a summary panel shows the summary for the DCT table. Update Add View Delete Search Exit Help FAADCT1 Destination Control Table More : Either type a new Destination Name and Group Name, or type / against a listed name. Then select one of the actions shown. / Destination Group Description _ CAEX FAASYS Import / export log _ CCBL FAASYS COBOL Message log _ CSCS FAASYS Security log _ CSMT FAASYS Error log _ _ _ _ _ _ Destination Name . . . . . . . . ____ Group Name. . . . . ________ Enter F1=Help F3=Exit F7=Backward F8=Forward F10=Actions F12=Cancel Example of a summary panel On the summary panel the action bar contains seven options. The default action is View, which is highlighted. Beneath the panel title line is the More: field, which shows if there are entries preceding (-), following (+), or both preceding and following (- +), those currently displayed. Use F7 and F8 to page backwards and forwards through the summary. If there are no more entries, the More field is blank. There follows a summary of up to 10 entries (on the first screenful) in the table. Next comes the name field, where you can type the name of an entry without having to page through the list of entries to find the required entry. If you both select entries and type a name, the named entry is processed first. On the above panel, the name field has the label "Destination" (on a Terminal Control Table panel it is called "Term", and on a File Control Table panel "Filename"). Each entry belongs to a group. The supplied group is FAASYS. For further details, see the description of the CICSRGRP environment variable in the CICS for OS/2 Customization book. The last line shows the function keys that you can use with they panel: they are described in Function keys. ═══ 7.2.3. Detail panels ═══ For this example, select CSCS (Security Log). With the highlighted action set to View (the default), press Enter. The detail panel for CSCS is displayed, see Example of a detail panel. Update Add View Delete Exit Help FAADCT2 Destination Control Table-1 Description Destination. . . . . . . : CSCS Group Name . . . . . . . : FAASYS Facility Type. . . . . . : L (L, E, R or I) Description. . . . . . . : Security log Intra-partition Recoverable Queue. . . . : U (R or U) Trigger level. . . . . . : 0 Transaction ID . . . . . : Terminal ID . . . . . . . . : Extra-Partition Input/Output . . . . . . : Fixed/Variable. . . . . . . : Device type. . . . . . . : Maximum record length . . . : Device/file name . . . . : Remote System ID. . . . . . . . : Record Length . . . . . . . : Remote Destination . . . : Indirect Indirect Dest. . . . . . : Enter F1=Help F3=Exit F10=Actions F12=Cancel Example of a detail panel If you return to the summary panel midway through your selections, you find the remaining selections still marked. You can then change the default action if you wish, and continue with the next selection. ═══ 7.2.4. The switch panel function ═══ Workstation users will already be familiar with the switch panel Alt/Esc key combination. On OS/2 workstations, CICS for OS/2 allows you to run several logical terminals on the workstation concurrently. You can switch between them by using the Alt/Esc combination. You can also use the Ctrl/Esc combination to display the OS/2 Window List, which allows you to switch sessions. ═══ 7.3. The CICS for OS/2 action bar ═══ The available actions are shown in the action bar at the top of a panel. They are described in detail in What the CICS for OS/2 actions do. ═══ 7.3.1. To perform an action: ═══ 1. Make selections from the panel.  For Update, View, and Delete, first select one or more entries from the list, then select an action.  For Add, either select the action first, or type a name for the new entry in the name field. Then select the action.  For Search, enter the name of an entry in the name field, and then select the action. To move between the actions, first press F10, and then use the Tab key. 2. Press Enter. A panel is displayed corresponding to the first selected entry, with the selected action highlighted. If you made more than one selection in the summary panel, any unprocessed selections remain marked, and you can continue with the next one by pressing Enter on the detail panel. An action selected on a summary panel is the default for all the entries selected in that summary. An action selected on a detail panel applies to that entry only. ═══ 7.3.2. What the CICS for OS/2 actions do ═══ The following actions are available with CICS for OS/2: Add Use with CEDA to add a new table entry. To add an entry: 1. Select Add on the summary panel and press Enter. 2. On the detail panel, add details for the entry as required. 3. To add the new entry, press Enter; to clear the name field ready for another entry, press Enter again; to redisplay the summary panel, press F3 or F12. You can also add an entry by copying the details of an existing entry. To do this: 1. Select the required entry on the summary panel. 2. Select View on the summary panel, and press Enter. 3. Select Add on the detail panel, and press Enter. 4. Update the entry as required. 5. To add the new entry, press Enter. Delete Use with CEDA or CSCA to delete a table entry or a map. To delete an entry: 1. Select the entry to be deleted. 2. Select Delete on the summary panel, or select Update or View on the summary panel, then Delete on the detail panel. 3. Press Enter. 4. To confirm deletion, press Enter again. To cancel deletion, press F12. Pressing F12 cancels the deletion, but still displays the entry. If you wish to delete a group of resources from the import/export file, use the CADL transaction as described in The CADL panel. Process Use with panels that perform one function, such as the CAIM panel, to begin processing. Search Use with CEDA and CSCA summary panels to scroll the name of an entry, or the place where the entry would occur, to the top of the summary. 1. Type the name of an entry in the name field. 2. Select Search. Update Use with CEDA to update an existing table entry. If Update is selected, the entry is displayed ready for you to change the fields. View This is the initial default action for the CEDA and CSCA panels. It displays selected table entries. Help Displays help information. Selecting the Help action has the same effect as pressing F1. Exit Move up one panel level. Selecting the Exit action has the same effect as pressing F3. ═══ 7.3.3. Example of using the actions ═══ This example gives you an opportunity to practice using some of the actions, using the CEDA transaction. Your local Signon Table (SNT) already contains at least one entry. The example adds a few more: 1. On the CICS for OS/2 command line, type: CEDA SNT This displays the local SNT summary panel. The cursor is in the selection column. 2. Tab to the User ID field and type BILL, then press F10 to move into the action bar. Tab to Add, and then press Enter. Add is highlighted, and the SNT detail panel is displayed. The cursor is in the User ID field, which says BILL. 3. Tab to the Password field. Type SPENCER, and then press Enter, letting the other fields default. A message confirming that the new user has been added to the SNT is displayed. Press Enter to clear the User ID field ready for the next entry. 4. Continue by repeating the same process for the next three entries, using this data:  User ID: DAVE Password: HEART  User ID: JO Password: THYME  User ID: SHIRLEY Password: TWAIN When you have completed the third entry, press F3 to redisplay the summary panel. The cursor is in the selection column. 5. Now check the entries. The summary panel is in alphabetic order of user ID. Press F7 to go to the start of the summary and select BILL by typing a slash (/) against it. Then select DAVE, JO, and SHIRLEY, paging forward if necessary. 6. To enable you to update the details for these entries, tab to Update, and press Enter. BILL's details are displayed. The highlighted action is Update. This entry is OK: press Enter to leave it as it is and display the next selection. 7. The next selection is DAVE; this is a practice entry and should be deleted entirely. Press F10 to move into the action bar and tab to Delete. Press Enter. The panel is redisplayed with Delete highlighted. Press Enter again. You are asked to confirm the deletion: press Enter. The deletion confirmation message is displayed. 8. Press Enter to display the next selection (JO). The default action (Update) is highlighted, and the cursor is in the Password field (because the first field is User ID, which you cannot change). This user is to be allowed access to the resource tables, so tab to the Authorized to use tables entry and change N to Y. Press Enter. The update confirmation message is displayed. 9. Press F3 to return to the summary panel. Page through it using F7 and F8, if necessary. The entry you deleted, DAVE, has gone; BILL and JO are there but unmarked. SHIRLEY was not updated, and is therefore still marked. This is the end of the example. Note: Normally you have to restart CICS for OS/2 before new CEDA entries can be used. However, SNT changes take effect immediately. ═══ 7.4. Reading CICS for OS/2 messages ═══ Messages appear in the CICS for OS/2 log window to inform you of the outcome of transactions entered. ═══ 7.4.1. Message types ═══ There are four types of message: I Information. These tell you what is happening. They do not indicate any errors. W Warning. These tell you that something is wrong, but it is unlikely to cause a problem. You are prompted to shut down the system or continue. E Error. These tell you that an error has occurred that is likely to cause a problem. Again, you are given the choice of shutting down CICS for OS/2 or ignoring the error and continuing. S Severe error. Here, the problem is so serious that CICS for OS/2 is unable to continue and must be shut down. ═══ 7.4.2. Browsing the CICS message log ═══ The CICS message log (CICSMSG.LOG) contains a list of all the messages recorded during your CICS for OS/2 session. A message line may contain the following information:  The APPLID of the system where the message was generated  The date and time the message was generated  The task that generated the message  The terminal (if there is one) that is owned by the task. If no terminal is owned by the task, the task identifier is repeated  The message number and message text. Usually only the message number and text are displayed, but all information is given if there are warning or error messages. After a cold start, only the messages for the current session are shown in the message log. The message log window contains two pulldown menus: View and Help. The View menu contains the following commands: Change View Displays a dialog box that allows you to select the messages that are displayed. You can select:  All messages  The messages for a particular task  The messages for a particular terminal. When you select messages using the Change View command, messages from previous sessions are displayed. Time stamp Allows you to switch off and on the date, time, task and terminal information in the message. Auto-scroll Allows you to switch off and on the scrolling of messages in the message log window. When you switch scrolling on, scrolling occurs automatically when new messages are added at the bottom of the window. The Help menu contains the following commands: Extended help Displays help on using the message log. Message help Displays help for a selected message. Product information Displays a CICS for OS/2 logo panel. You can obtain help for a particular CICS for OS/2 message by:  Double-clicking on the message line for the CICS for OS/2 message  Clicking on the message line and then selecting Message help from the Help pulldown.  Pressing F1 after clicking on the message. If an error occurs during initialization for a cold or warm start, two buttons Shutdown and Continue appear at the bottom of the message log window. You can then shut down CICS for OS/2 or ignore the error and continue. ═══ 7.4.3. Using the FFST/2 log ═══ In those systems where it is available, CICS for OS/2 also writes messages to the FFST/2 system error log OS2MLOG.DAT, with the exception of those messages of type I (information). To view the log, click on the Message Log Formatter icon in the RAS folder, which is located within the CICS for OS/2 folder. ═══ 7.5. Getting help in CICS for OS/2 ═══ For details about obtaining help in CICS for OS/2, see Viewing product help. ═══ 7.6. Using the mouse and the keyboard ═══ This section describes the use of the mouse and the keyboard with CICS for OS/2 ═══ 7.6.1. Moving the cursor in a panel ═══ Generally, the cursor control keys on a workstation work as on a mainframe-attached 3270 terminal. You can use Tab and Backtab (shift tab) to move the cursor from field to field (and from one action to another in the action bar), and F10 to move directly to the action bar. Alternatively, you can use a mouse to move the cursor and to select fields that have been defined as light-pen detectable. To select the field, simply point to the desired location on the panel and click twice. Note: You cannot use the mouse in this way in a client transaction routing session. The supplied keyboard configuration is described in the next section. If you have access to CEDA, you can reassign the keyboard functions. ═══ 7.6.2. The supplied keyboard configuration ═══ ═══ 7.6.2.1. Keyboard setup ═══ A keyboard setup is not supplied, but if you attempt to add a Workstation Setup (WSU) table entry, the WSU panels initially indicate the default key assignments. For more information refer to the CICS for OS/2 Customization book. ═══ 7.6.2.2. The Enter key ═══ In the system as supplied, the right-hand Ctrl key acts as the CICS Enter key. Note: The Enter key is assigned differently on different types of keyboard. However, Ctrl-Enter works as the CICS Enter key on all types of keyboard. ═══ 7.6.2.3. Function keys ═══ There are six function keys. The standard assignments are listed below, and are shown on the CICS for OS/2-supplied transaction panels to which they apply. All functions can be reassigned using CEDA. F1 Help Display help information. Selecting the Help action has the same effect as pressing F1. Help information is available for panels and for messages. Pressing F1 when a panel is displayed gives the help information for that panel. There can be more than one page of information. Pressing F1 when a message is displayed gives the help information for that message. Press F3 to exit from the help display. You can also use the CHLP transaction, and the CICSHELP command, to display help panels; see Viewing product help. F3 Exit Move up one panel level. Selecting the Exit action has the same effect as pressing F3. F7 Bkwd Page backward. F8 Fwd Page forward. F10 Actions Move the cursor to the action bar, or from the action bar back to the panel body. F12 Cancel Move to the next panel without processing the one displayed. For example, if you press F12 in response to a message asking you to confirm a deletion, the entry is not deleted, but its details remain displayed. ═══ 7.6.2.4. Other keys ═══ The following keys have specific functions: Alt + P Print the panel. A printer must be attached to the terminal. Esc Clear the panel. The panel switch function (Alt+Esc) is described in The switch panel function. ═══ 8. Supplied transactions ═══ This topic  Describes the use of the transactions supplied with CICS for OS/2. Transactions and command files differ in the following ways:  Transactions can be run only when CICS for OS/2 is operating, and are entered in an open terminal window.  Command files have the extension .CMD and can be run only from the OS/2 command line or from other command files. Command files can be run without CICS for OS/2 running. When you create new transactions or files, take care that their names do not conflict with those supplied. Transaction names starting with the letter `C' or command file names starting with CICS or FAA are reserved for use by CICS for OS/2. Many of the supplied transactions that display panels use an action bar that shows the actions available. The action bar enables you to perform several related functions within one command rather than having to use separate commands. See The CICS for OS/2 action bar for more information. ═══ 8.1. Transactions supplied by CICS for OS/2 ═══ CICS for OS/2 transactions shows the transactions supplied with CICS for OS/2. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 2. CICS for OS/2 transactions │ ├───────────────┬───────────────────────────────────────────────┬──────────────┤ │ TRANSACTION │ FUNCTION │ TOPIC │ │ │ │ DESCRIBED │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CADL │ Delete application group │ The CADL │ │ │ │ panel │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CAEX │ Export application group │ The CAEX │ │ │ │ panel │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CAIM │ Import application group │ The CAIM │ │ │ │ panel │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CEBR(**) │ Browse temporary storage queues │ Browsing │ │ │ │ temporary │ │ │ │ storage and │ │ │ │ transient │ │ │ │ data │ │ │ │ queues-CEBR │ │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CECI(**) │ Invoke command level interpreter │ Invoking the │ │ │ │ command │ │ │ │ level │ │ │ │ interpreter-C│CI │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CEDA │ Define resources │ Defining │ │ │ │ resources-CED│ │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CEDF(**) │ Start EDF (debugging) │ Starting │ │ │ │ debugging-CED│ │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CEMT │ Control resources │ The CEMT │ │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CEPN │ Connect and disconnect CICS for OS/2 inter- │ Connecting │ │ │ face to PNA │ and discon- │ │ │ │ necting from │ │ │ │ PNA-CEPN │ │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CESF │ Sign off workstation │ Signing off │ │ │ │ a │ │ │ │ workstation-C│SF │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CESN │ Sign on │ Signing │ │ │ │ on-CESN │ │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CETR │ Enable/disable trace │ Setting up │ │ │ │ trace-CETR │ │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CHLP │ Get help for message, panel, or abend code │ Viewing │ │ │ │ product help │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CLOG │ Display IBM logo │ Signing │ │ │ │ on-CESN │ │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CMLV │ View Message Log │ The Message │ │ │ │ Log viewed │ │ │ │ using CMLV │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CPOP │ Control the PL/I Interactive Test Facility │ Controlling │ │ │ │ the PL/I │ │ │ │ Interactive │ │ │ │ Test │ │ │ │ Facility-CPOP│ │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CQIT │ Shut down the system │ Shutting │ │ │ │ down the │ │ │ │ system │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CRTE │ Perform transaction routing │ Running │ │ │ │ remote │ │ │ │ transactions-│RTE │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CSCA │ View and delete user map sets │ Viewing and │ │ │ │ deleting │ │ │ │ user map │ │ │ │ sets-CSCA │ │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ CSFE │ Perform storage control │ Performing │ │ │ │ storage │ │ │ │ control-CSFE │ │ │ │ transaction │ ├───────────────┼───────────────────────────────────────────────┼──────────────┤ │ EXIT │ Close terminal window │ Disconnecting│ │ │ │ a terminal │ └───────────────┴───────────────────────────────────────────────┴──────────────┘ The following topics describe the supplied transactions in alphabetic order and in terms of the user tasks supported. The CEMT transaction is described separately in The CEMT transaction. ═══ 8.2. Deleting an application group-CADL transaction ═══ Use the CADL transaction to delete application groups from the export file or from the backup file. The CADL transaction displays the Import/Export Summary panel, which you use to delete application groups from the export file or from the backup file. (See The CADL panel.) See The CAEX panel for the use of import and export files. The group specified in a CADL panel must previously have been exported from the source workstation using CAEX. View Delete Search Main Backup Exit Help FAAAED1 Import/Export Summary Type a name at the prompt, or enter a / against a listed group name. Then select an action from the action bar and press ENTER. Main file Backup file / Group name / Group name _ FAAIVP _ FAASAMPL _ FAASYS _ _ _ _ _ _ _ Group Name. . . . ________ Enter F1=Help F3=Exit F7=Backward F8=Forward F10=Actions F12=Cancel The CADL panel ═══ 8.2.1. Using the CADL transaction ═══ The CADL panel lets you select groups and carry out actions on them. To select a group, either type its name in the Group Name field and press Enter, or type a slash (/) against the name and press Enter. You can select more than one group. To choose whether to carry out actions on a main or a backup file, either type the slash in the appropriate column, or use the Main and Backup actions to switch between the two. The View action lets you display the names of the groups on the main or backup files. It does not display the contents of a group. The Delete action lets you delete groups from the system. After selecting or naming them, move the cursor to Delete and press Enter to display the first group, then confirm the deletion. The Search action scrolls the group name specified in the name field to the top of the panel. The Main action makes the import/export file (FAAAEFIE.BTR) available for viewing and deletion. The Backup action makes the backup file, FAAAEFBU.BTR, available for viewing and deletion. ═══ 8.3. Exporting an application group-CAEX transaction ═══ Use the CAEX transaction to export an application group. Exporting means copying the entire group of resources required for an application, from CICS for OS/2 to the import and export file (FAAAEFIE.BTR). An application group:  Includes programs, BMS map sets, CICS for OS/2 control table entries, and file definitions; and can include data files.  Is defined by specifying a common group name in the CEDA definition of each member. The CAEX transaction displays the panel shown in The CAEX panel. ═══ 8.3.1. Using the CAEX transaction ═══ Before entering the CAEX transaction, you must ensure that all the resources to be exported have been defined by CEDA in one or more groups. You may use the wildcard characters asterisk (*) and question mark (?) for generic group names. You must also ensure that all the resources such as file definitions reside in the directory specified in the file control table (FCT). Program .DLL resources must be located in the path defined by the CICSWRK environment variable. Data files must also be set closed to CICS before entering the transaction. Process Help Exit FAAAEN2 Application Export Type in group name and press 'Enter' The group name can contain a '?' in individual character positions to indicate any character. An '*' at the end of the group name indicates any group of characters Group Name . . . . . . . . . . . . . . . . ________ Include Conversion Templates . . . . . . . N (Y/N) Include SNT . . . . . . . . . . . . . . . Y (Y/N) Export SNT and CVT in group . . . . . . N (Y/N) Include data files . . . . . . . . . . . . Y (Y/N) Enter F1=Help F3=Exit F10=Actions The CAEX panel Group Name This is a required field in which you must type the name of an export group. The name can consist of the following characters: A through Z, 0 through 9, @, #, $. Lowercase letters are converted to uppercase. In addition, a question mark (?) can be used to represent a single character in any position, and an asterisk (*) can be used to represent one or more characters at the end of the group name. Include Conversion Templates Do you want to export the conversion templates with the application? The default is No. Include SNT Do you want to export the SNT with the application? The default is Yes. Be careful when exporting an SNT. If a user ID on the importing system is the same as one in the exported SNT, the password for the user ID on the importing system is overwritten by the password on the exported SNT. Export SNT and CVT in group Do you want to include the SNT or data conversion templates table (CVT) entries? The default is No. Include data files Do you want to export the data files with the application? The default is Yes. When you have typed in the fields, select Process and press Enter. ═══ 8.3.2. Further information ═══ CAEX exports to the import and export file (FAAAEFIE.BTR in the \DATA subdirectory) programs, files, BMS map sets, and control table entries defined with the entered group name in the control tables. You can use CAEX and CAIM to migrate resources from a previous version of CICS for OS/2. How to do this is described in the CICS for OS/2 Installation book. If (1) CAEX cannot find a mapset or program specified in the group PPT, (2) an existing record is overwritten, or (3) there is an open or read error on the program file, a warning message is put on the temporary storage (TS) queue CEBRxxxx, where xxxx is your terminal ID. The CAEX transient data destination is used as a log file. This may be viewed offline to determine which resources have been exported. If the destination is not defined, messages are written only to the TS queue. For more information on exporting an application group, see the CICS for OS/2 Customization book. ═══ 8.4. Importing an application group-CAIM transaction ═══ Use the CAIM transaction to import an application group. Importing means copying the entire group of resources required for an application, from a local or remote file, to CICS for OS/2. The group specified in the CAIM panel must previously have been exported from a workstation using CAEX. You import an application group from the import and export file (FAAAEFIE.BTR), or from the backup file (FAAAEFBU.BTR), both of which are initially empty. A backup of the transaction resource definitions shipped in CICS for OS/2 is provided in FAAAEFIE.BAK. ═══ 8.4.1. Using the CAIM transaction ═══ The CAIM panel is shown in The CAIM panel. Process Help Exit FAAAEN1 Application Import Type in group name and press 'Enter' The group name can contain a '?' in individual character positions to indicate any character. An '*' at the end of the group name indicates any group of characters Group Name . . . . . . . . . . . . . . . . ________ Include Conversion Templates . . . . . . . N (Y/N) Include SNT . . . . . . . . . . . . . . . Y (Y/N) Include data files . . . . . . . . . . . . Y (Y/N) Import from Backup file . . . . . . . . . N (Y/N) Backup Existing Data . . . . . . . . . . . Y (Y/N) Enter F1=Help F3=Exit F10=Actions The CAIM panel Group Name This is a required field in which you must type the name of an application group. The name can consist of the following characters: A through Z, 0 through 9, @, #, $. Lowercase letters are converted to uppercase. In addition, a question mark (?) can be used to represent a single character in any position, and an asterisk (*) can be used to represent one or more characters at the end of the group name. If an existing record is overwritten, or if there is an open or write error on the program file, a warning message is displayed and return codes are written to temporary storage (TS) queue CEBRxxxx, where xxxx is your terminal ID. The CAEX transient data destination is used as a log file. This may be viewed offline to determine which resources have been imported. If the destination is not defined, messages are written only to the TS queue. Include Conversion Templates Do you want to import the conversion templates with the application? The default is No. Include SNT Do you want to import the SNT with the application? The default is Yes. Be careful when importing an SNT. If a user ID on the importing system is the same as one in the imported SNT, the password for the user ID on the importing system is overwritten by the password on the imported SNT. Include data files Do you want to import the data files with the application? The default is Yes. Import from Backup file Do you want to import the application from a backup file rather than the import and export file? The default is No. Backup Existing Data Do you want to copy the old version of the application to the backup file? The default is Yes. You cannot do this if you are importing the application from the backup file. This field applies only when you are importing a new version of an application that is already on the workstation. When you have typed in the fields, select Process and press Enter. ═══ 8.4.2. Further information ═══ You can use CAEX and CAIM to migrate resources from a previous version of CICS for OS/2. How to do this is described in the CICS for OS/2 Installation book. For more information on importing an application group, see the CICS for OS/2 Customization book. ═══ 8.5. Browsing temporary storage and transient data queues-CEBR transaction ═══ Use the CEBR transaction to browse the contents of temporary storage and transient data queues. ═══ 8.5.1. Further Information ═══ This transaction is described in the CICS for OS/2 Application Programming book. ═══ 8.6. Invoking the command level interpreter-CECI transaction ═══ Use the CECI transaction to enter CICS for OS/2 instructions (as in the EXEC CICS API), check their syntax, and execute them interactively. CECI operates as it does in mainframe CICS. ═══ 8.6.1. Further Information ═══ This transaction is described in the CICS for OS/2 Application Programming book. ═══ 8.7. Defining resources-CEDA transaction ═══ Use the CEDA transaction to define in control tables the resources (for example, terminals, programs, and files) with which CICS for OS/2 will be working. The CEDA transaction defines all resources on CICS for OS/2. CICS for OS/2 provides no facilities for defining resources by means of macros. Access is provided to the CEDA transaction by the system administrator. The user must also have signed on using CESN. ═══ 8.7.1. Using the CEDA transaction ═══ Entering CEDA will bring up the panel shown in The CEDA panel. CEDA also has a command line interface which allows panels to be bypassed by adding the appropriate parameters. Process Exit Help FAAEDA1 Resource Definition Online Type / against a Table Name. Then select one of the actions shown. / Table Description _ CVT Data Conversion Table _ DCT Destination Control Table _ FCT File Control Table _ PCT Program Control Table _ PPT Processing Program Table _ SIT System Initialization Table _ SNT Signon Table _ TCS Connection and Session Table _ TCT Terminal Control Table _ TST Temporary Storage Table _ WSU Workstation Set Up _ GRP Group Processing Enter F1=Help F3=Exit F10=Actions F12=Cancel The CEDA panel ═══ 8.7.2. Further Information ═══ See the CICS for OS/2 Customization book for more detail. ═══ 8.8. Starting debugging-CEDF transaction ═══ Use the CEDF transaction, which starts the execution diagnostic facility (EDF), to debug programs at the CICS command level. ═══ 8.8.1. Further Information ═══ The CEDF transaction is described in the CICS for OS/2 Application Programming book. ═══ 8.9. Controlling system resources-CEMT transaction ═══ Use the CEMT transaction to query and set the status of the resources in a CICS for OS/2 system. See The CEMT transaction for details. ═══ 8.10. Connecting and disconnecting from PNA-CEPN transaction ═══ On a CICS for OS/2 multi-user system, use the CEPN transaction to connect and disconnect the CICS for OS/2 interface from PNA, and to display the current status of the interface. PNA terminals are unable to attach to CICS for OS/2 until the PNA Interface is successfully enabled. The CEPN panel is shown in The CEPN panel. Enter one of the following: Close Open Inq Enter PF1=Help PF3=Exit The CEPN panel ═══ 8.10.1. Using the CEPN transaction ═══ Close Use this option to disconnect the CICS for OS/2 interface from PNA. Open Use this option to connect the CICS for OS/2 interface to PNA. Inq Use this option to check the status of the CICS for OS/2 interface with PNA. ═══ 8.10.2. Further Information ═══ See Programmable Network Access (PNA) Support for further information. ═══ 8.11. Signing off a workstation-CESF transaction ═══ Use the CESF transaction to sign off from CICS for OS/2. ═══ 8.11.1. Using the CESF transaction ═══ If you enter CESF without the optional LOGOFF parameter, you are signed off from CICS for OS/2. Your terminal is still connected to CICS, but only unsecure transactions can be run. If you specify the LOGOFF parameter, your terminal is disconnected from CICS. The LOGOFF parameter is not valid when transaction routing. This includes the CRTE transaction, and transactions being run from client terminals. ═══ 8.12. Signing on-CESN transaction ═══ Use the CESN transaction to sign on to CICS. In the supplied system, the initial Sign-on panel (see The initial sign-on panel) is displayed immediately after the CICS for OS/2 logo panel. If you have security clearance, you may sign on to CICS for OS/2 to run transactions or to access the resource definition tables. If you have no security clearance, you can begin using unsecured transactions by pressing F3 at this point. You can change the user ID for a session by issuing a CESN transaction when you are already signed on. Your previous user ID is signed off by the system and you are signed on with the new user ID. ═══ 8.12.1. Using the CESN transaction ═══ With CESN you have the option of entering the complete transaction (including keywords) on the command line, or entering CESN alone and using the panels which are then displayed. If you enter the complete transaction, the format is as follows: CESN [USERID=userid] [PS=password] [NEWPS=newpassword] You can enter the keywords in any order, and can give them any value from 1 to 8 alphanumeric characters. The sign-on is attempted as long as you specify the USERID keyword. If you do not then the other keywords are ignored and the initial sign-on panel is displayed. This panel is also displayed if you make any errors when entering the transaction text. If you enter CESN without keywords, the initial sign-on panel is displayed as shown below: FAACESN CICS Sign-on Type your userid and password : Userid. . . . . . . . . . . . . . : Password. . . . . . . . . . . . . : New password. . . . . . . . . . . : Security Manager in use . . . . . : SNT Enter F1=Help F3=Exit The initial sign-on panel Enter values for the following fields, as required. Entries must contain between 1 and 8 alphanumeric characters. Userid Type in your user ID and press the Tab key. Password Type in your current password. This is not displayed. New password Type in your new password. This is not displayed. Press Enter. If you entered a new password, you will be presented with a second panel to confirm it, as shown in The confirm sign-on panel. Otherwise the sign-on will be attempted. FAACESN CICS Sign-on Type your userid and password : Userid. . . . . . . . . . . . . . : TONY Password. . . . . . . . . . . . . : Confirm new password. . . . . . . : Security manager in use . . . . . : SNT FAA2269I (CHUCK) Please re-enter the new password to confirm, F3 to exit Enter F1=Help F3=Exit The confirm sign-on panel Note: 1. The CESN transaction allows you only 3 attempts at signing-on. After the third attempt the transaction ends. 2. Starting the CESN transaction signs off your user ID, even if you do not complete the transaction. You are then required to sign on again using your existing user ID. ═══ 8.12.2. Further Information ═══ For APPC links to a mainframe, security is defined by the mainframe CICS system as local or verify. Security is also defined in the Connection and Session Table (TCS) and in Communications Manager. See the CICS for OS/2 Customization book for further information. These definitions will determine whether or not you need to sign on. ═══ 8.13. Setting up trace-CETR transaction ═══ Use the CETR transaction to set trace levels or turn on the trace file. Entering the transaction displays the panel shown in The CETR trace control panel.. To identify system problems, it may be necessary to take a trace to help your systems administrator, or support organization, to identify your problem. Update Exit Help FAATRC1 Tracing Options Turn an option on by typing 'Y'. Turn an option off by typing 'N'. Then select update action to implement options Trace file active. . . . N Overwrite existing file. . . . . . N Standard tracing levels - Major routine. . . . . . N Routine . . . N Section . . . . . N Standard tracing points - Entries. . . . . . . . . N Errors. . . . N Events. . . . . . N Facility name. . . . . . ____ Transaction name . . . . . ____ Trace file name. . . . . D:\CICS300\RUNTIME\FAATAFEN.TRC___________________ Communications tracing - Non APPC trace . . . . . N Enter F1=Help F3=Exit F10=Actions F12=Cancel The CETR trace control panel. ═══ 8.13.1. Using the CETR transaction ═══ The entries shown when you call up the panel are those last set, with one exception: the Overwrite existing file field always defaults to `N'. If the Facility name or the Transaction name fields are not specified, underscores are shown for those entries. The Trace file name field shows the default path name C:\CICS300\RUNTIME\FAATAFEN.TRC, unless a new file name is specified. ═══ 8.13.2. Further Information ═══ For more information about the CETR transaction, and about using the CICSFMT command to print trace and dump files, see the CICS for OS/2 Problem Determination book. ═══ 8.14. Getting online help-CHLP transaction ═══ Use the CHLP transaction to get online help for CICS messages, panels, and abend codes. See Viewing product help for details. ═══ 8.15. Viewing the Message Log-CMLV transaction ═══ Use the CMLV transaction to view the Message Log at the server machine from any CICS terminal connected with transaction routing enabled. The Message Log viewed using CMLVshows the panel displayed when you enter CMLV at a remote terminal. Time CICS Message Log Viewer Run Time 14:10:39 00:33:30 15-01-96 9:56:18a MAIN MAIN FAA3243E Message not retrieved: FAA0000I (OS/2,3. 15-01-96 9:56:18a MAIN MAIN FAA3243E Message not retrieved: FAA0001I (00, UL0 15-01-96 9:56:18a MAIN MAIN FAA3243E Message not retrieved: FAA0003I (CICS) 15-01-96 9:56:21a MAIN MAIN FAA3243E Message not retrieved: FAA0061W (0000002 15-01-96 9:56:22a MAIN MAIN FAA3243E Message not retrieved: FAA1672S () 15-01-96 9:56:26a MAIN MAIN FAA3243E Message not retrieved: FAA5561I () 15-01-96 10:01:21a MAIN MAIN FAA0000I CICS for OS/2 Version 3.0 15-01-96 10:01:21a MAIN MAIN FAA0001I Service Level 00, UL00000. Released 11-J 15-01-96 10:01:21a MAIN MAIN FAA0003I CICS system initialization starting 15-01-96 10:01:26a MAIN MAIN FAA0060I System Configuration updated successfull 15-01-96 10:01:27a MAIN MAIN FAA1698I System Initialization Table loaded from 15-01-96 10:01:28a MAIN MAIN FAA1660I Initialization for System CICS, Appl ID 15-01-96 10:01:29a MAIN MAIN FAA1699I System File Manager Version 6.20 loaded 15-01-96 10:02:27a MAIN MAIN FAA8806I There are 89 days left in the Evaluation 15-01-96 10:02:28a MAIN MAIN FAA1710I Using CICSUserMap environment variable t 15-01-96 10:02:28a MAIN MAIN FAA1710I Using CICSSystemMap environment variable 15-01-96 10:02:29a MAIN MAIN FAA1690I CICSRGRP not specified. All groups loade 15-01-96 10:02:46a @01@ V123 FAA1670I Terminal task, task ID = V123 F1=Help F3=Exit F4=Top F5=Bottom Appl ID F7=Backward F8=Forward F10=Left F11=Right CHUCK The Message Log viewed using CMLV ═══ 8.16. Controlling the PL/I Interactive Test Facility-CPOP transaction ═══ Use the CPOP transaction to provide control over the PL/I interactive Test Facility (PLITEST), which is used for source-level debugging of PL/I programs. CPOP allows you to enable and disable PLITEST debugging, and control when and how PLITEST is invoked. This applies only to the terminal that the CPOP transaction is run from. To enable PLITEST to debug a CICS PL/I application program, it must be compiled with the TEST compiler option (see the CICS for OS/2 Application Programming book). Also, the CEE.OPTIONS runtime option TEST must be in effect. CPOP may be used to set the TEST runtime option and thereby control PL/I debugging. The CPOP panel allows you to display and update the options and suboptions of the TEST runtime option. The CPOP transaction allows you to select either of two options: ┌─ERROR─┐ ┌─*─┐ ┌─PROMPT───┐ ┌─*─┐ ┌─TEST──(──┼───────┼──,──┴───┴──,──┼──────────┼──,──┴───┴──)─┐ │ ├─ALL───┤ ├─NOPROMPT─┤ │ │ └─NONE──┘ ├─;────────┤ │ │ └─*────────┘ │ >>──┼────────────────────────────────────────────────────────────┼────────────>< └─NOTEST─────────────────────────────────────────────────────┘ TEST PLITEST is invoked, dependent on the specified suboptions: ALL PLITEST is given control when any PL/I condition occurs, even without a defined breakpoint. ERROR PLITEST is given control when an ERROR or ATTENTION condition occurs. This is the default. NONE No condition can give control to PLITEST without a defined breakpoint. PROMPT PLITEST is invoked at the first PROCEDURE statement or BEGIN BLOCK of the PL/I program. This is the default. NOPROMPT PLITEST is not invoked until it is explicitly called by a CALL PLITEST statement. NOTEST PLITEST is not invoked unless a CALL PLITEST statement is executed. For more information about PLITEST and PL/I programming, see the PL/I for OS/2 Programming Guide. ═══ 8.17. Shutting down the system-CQIT transaction ═══ Use the CQIT transaction to shut down the system. See Shutting down the system for details. ═══ 8.18. Running remote transactions-CRTE transaction ═══ Use the CRTE transaction to run a transaction that resides in a remote system. CRTE can be entered from a locally attached terminal, or from a client workstation (to route from the CICS for OS/2 server). Transaction routing is usually achieved by making entries in the PCT to define a transaction as remote, and naming the remote system on which it runs. If the remote system is CICS for OS/2, and routing is over APPC links rather than NetBIOS or TCP/IP, it also must have an entry in Communications Manager for each transaction for which it expects to receive transaction routing requests. However, if you use CRTE, you do not have to make special entries in your local PCT (any such entries are ignored). Also, if the remote system is CICS for OS/2, and routing is over APPC links, the remote system need only define one transaction (CRTE) in Communications Manager for all incoming transaction routing requests. You should use CRTE, rather than making special PCT entries, to perform seldom-used transactions. ═══ 8.18.1. Using the CRTE transaction ═══ Enter the following: CRTE SYSID=sysid where sysid is the name of the system that is to execute the transaction. This must match one of the installed entries for the Connection name field in the local TCS. In response to the CRTE transaction, the routing transaction verifies whether the specified remote system is known. If it is, a message is displayed confirming that a routing session to the required system has been started. You can then clear the panel and enter the transaction code for the transaction that is to be executed on that system. In fact, you use the terminal as if it were connected directly to the remote system. However, you might be asked to sign on in that system before being allowed to run any transactions. You end a routing session by entering CANCEL. This automatically signs you off from the connected system. When a routing session is ended, you get the message: FAA5120I [applid] routing session to system 'SYSID' terminated ═══ 8.18.2. Further Information ═══ You must use CRTE when EDF is used to test a transaction running on a remote system. However, because the session has to be established and canceled explicitly, additional signon operations may be required. Note: 1. You cannot use PA or PF keys to invoke transactions under CRTE. 2. The transactions invoked can include pseudoconversational transactions. ═══ 8.19. Viewing and deleting user map sets-CSCA transaction ═══ Use the CSCA transaction to view and delete user map sets. The CSCA transaction displays a summary panel showing map sets that have been translated. Note: System-supplied maps cannot be viewed using this transaction. ═══ 8.19.1. Further Information ═══ The CSCA transaction is described in the CICS for OS/2 Application Programming book. ═══ 8.20. Performing storage control-CSFE transaction ═══ Use the CSFE transaction to provide control over the storage manager. This helps in debugging transactions that are experiencing storage violations or unexpected results that you suspect may be related to storage management. The CSFE panel is shown in The CSFE panel. ═══ 8.20.1. Using the CSFE transaction ═══ There are two debugging options, which can be selected separately or together: 1. Storage Freeze, which lets you enable or disable storage freezing either system-wide, or on a transaction-by-transaction basis. 2. Storage Check, which lets you enable or disable storage violation checking for all tasks or the current task. Disabling storage checking reduces system overhead. FAASFE1 Storage Debugging Options To select the Storage Freeze option, enter Y and a Transaction ID below: Storage Freeze . . . : N Y or N Transaction ID . . . : To select the Storage Check option, enter A or C below: Storage Check. . . . : N A = All Tasks C = Current Terminal only N = None Terminal ID. . . . . : Enter F1=Help F3=Exit The CSFE panel Storage Freeze Type Y to enable storage freezing. Storage freezing delays the release of storage until the end of a transaction rather than the time of the FREEMAIN request. Transaction ID If you enable storage freezing, you must type a transaction ID. Storage Check Type one of the following letters: A To specify storage violation checking for all tasks. C To specify storage violation checking for the current task only. N To specify that no storage violation checking is performed. When you select this option, every piece of storage owned by a task is checked at every entry, instead of at the time of a FREEMAIN request. Thus any storage violations are detected sooner. Terminal ID This indicates the terminal for which storage checking is currently active. ═══ 8.20.2. Further Information ═══ For more information about storage control, see the CICS for OS/2 Application Programming book. ═══ 8.21. Closing a terminal window-EXIT transaction ═══ Use the EXIT transaction to close a terminal window created by an ETI-initiated transaction. See Shutting down the system for details. ═══ 9. The CEMT transaction ═══ This topic  Describes the use of the CEMT transaction to control system resources. Use CEMT to inquire about and alter the status of system resources, terminate tasks, and shut down the CICS system. With CEMT you have the option of entering a complete request on the command line, or constructing a request in stages, using a series of panels which list the permitted values for the relevant parameter. You can use CEMT with both the INQUIRE and SET actions to provide a status display of resources in the CICS system. You can then alter the value of certain status fields by overtyping them. Alternatively, you can use CEMT SET with the appropriate parameters to alter the status of resources directly from the command line. ═══ 9.1. The CEMT command line ═══ Enter a CEMT request in the following format: CEMT action resource(value) operand(value) operand(value)....... where the parameters are defined as: action The action you wish to take. Permitted options are INQUIRE, SET and PERFORM. resource The resource type to be acted upon. The PERFORM action does not act upon specific resources, and only accepts an operand of SHUTDOWN. Use the value associated with the resource parameter to specify resources. For example, to display the status of terminal TRM1 enter: CEMT INQUIRE TERMINAL(TRM1) The default for value is ALL. operand A status value valid for the defined action and resource type. For example, to set all terminals in the system in service, enter: CEMT SET TERMINAL ALL INSERVICE. The associated value is optional. If you enter an invalid parameter as part of a CEMT request the appropriate level of panel is displayed to help you complete the request correctly. If you enter a valid resource or a status value for which there is no match in the CICS system, then a NOT FOUND response is returned. ═══ 9.2. Abbreviating input ═══ When entering CEMT requests, you can use an abbreviated format for each keyword, by entering only as many characters as are needed to uniquely identify it. The permitted abbreviations are shown in uppercase characters, both in the CEMT panels and in the syntax diagrams listed later in this topic When entering a value associated with a resource, you can use a + symbol to represent a single character, or a * symbol to represent a string of characters as any part of the value. Using these characters allows you to specify a group of resources, as in: CEMT INQUIRE TERMINAL(TRM*) to display the status of terminals whose id starts with TRM. ═══ 9.3. The CEMT panels ═══ The CEMT panels provide you with a list of the permitted options for each parameter, which you can then enter on the command line at the top of the panel. Enter CEMT without parameters to see an initial panel listing the three permitted actions, as shown in The initial CEMT panel. Status. . : Enter one of the following Inquire Perform Set Sysid= CICS Applid= CHUCK PF 1 Help 3 End The initial CEMT panel If you enter INQUIRE on this initial panel, a list is displayed of the system resource types on which you can take action, as shown in The CEMT resources panel after entering INQUIRE. If you enter SET, a similar panel is displayed, as shown in The CEMT resources panel after entering SET. If you enter PERFORM, panel The CEMT panel after entering PERFORM is displayed. In this case, only the SHUTDOWN option may be entered. INQUIRE Status. . : Enter one of the following or hit Enter for default Auxtrace Connection File Modename Netname Program System TAsk TClass TDqueue TErminal TRansaction TSqueue Sysid= CICS Applid= CHUCK PF 1 Help 3 End 12 Cancel The CEMT resources panel after entering INQUIRE SET Status. . : Enter one of the following or hit Enter for default Auxtrace Connection File Netname Program System TAsk TClass TDqueue TErminal TRansaction Sysid= CICS Applid= CHUCK PF 1 Help 3 End 12 Cancel The CEMT resources panel after entering SET The list of resources has SYSTEM highlighted as the default resource type for both the INQUIRE and SET actions. The subsequent system status panel can be viewed simply by pressing ENTER. If you enter one of the listed resource types, details of status for all resources of that type are displayed in a further panel, unless you add an identifier for a specific resource or group of resources. For example, entering PROGRAM at this point causes the panel shown in The CEMT status panel after entering PROGRAM to be displayed, whereas entering PROGRAM(FAAATSTR) limits the display to information only about that program. PERFORM Status. . : Enter one of the following SHUTdown Sysid= CICS Applid= CHUCK PF 1 Help 3 End 12 Cancel The CEMT panel after entering PERFORM Entering SHUTDOWN on this panel starts a normal shutdown of the CICS for OS/2 system. Entering SHUTDOWN I starts an immediate shutdown. In both cases, the effect is the same as when a CQIT transaction is used to close the system. See Shutting down the system for details. INQUIRE PROGRAM Status. . : Results - overtype to modify Prog(FAAAEPDL) Cob Pro Ena Sha Res(000) Use(0000005) Any Cex Ful Prog(FAAAEPMN) Cob Pro Ena Sha Res(000) Use(0000008) Any Cex Ful Prog(FAAATPCI) Cob Pro Ena Sha Res(001) Use(0000010) Any Cex Ful Prog(FAAATSSH) Pro Ena Sha Res(000) Use(0000000) Any Cex Ful Prog(FAAATSTR) Pro Ena Sha Res(000) Use(0000000) Any Cex Ful Prog(FAACTPCM) Cob Pro Ena Sha Res(000) Use(0000021) Any Cex Ful Prog(FAACTPCN) Cob Pro Ena Sha Res(000) Use(0000019) Any Cex Ful Prog(FAACTPDC) Cob Pro Ena Sha Res(000) Use(0000006) Any Cex Ful + Prog(FAACTPED) Cob Pro Ena Sha Res(000) Use(0000070) Any Cex Ful Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 15:52:59 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel The CEMT status panel after entering PROGRAM The format of the status panel is the same for both the INQUIRE and the SET actions. ═══ 9.4. Overtyping a display ═══ You can change the highlighted values in the panel by moving the cursor to the field and overtyping the existing value. When you press the ENTER key, CICS reads the contents of all fields that have been changed, and processes any valid operations implied by the changes. If you make an invalid change, you get an error message, and the field is not changed. On some status displays, status values positioned at the right-hand side of the display appear only when the status of a particular resource is `on'; for other resources, it appears only when the status is `off'. You can still overtype these status fields whether they are displayed or blank. ═══ 9.5. Tabbing to fields ═══ The fields you can change are different in each display. You can detect them, however, by pressing the tab key repeatedly. This causes the cursor to jump from one field to the next. ═══ 9.6. Scrolling symbol (+ sign) ═══ A plus (+) sign on the first or last line of a display tells you that there is more data above or below your current display. Scrolling backward reveals data above, and scrolling forward reveals data below. ═══ 9.7. Program function (PF) keys ═══ Here is what the PF keys do: PF1 is a general HELP key. It also gives you a list of all the PF keys and what they do. PF3 ends this master terminal session by terminating the CEMT transaction. PF7 scrolls backward a full screen. PF8 scrolls forward a full screen. PF9 displays any messages generated by the last command entered. PF12 returns to the previous panel. ═══ 9.8. CEMT INQUIRE AUXTRACE ═══ CEMT INQUIRE AUXTRACE Function Retrieve information about the status of auxiliary trace. Description Auxiliary trace entries are made to an auxiliary trace file. INQUIRE AUXTRACE tells you:  Whether the auxiliary trace file is open or closed  That the auxiliary trace file is active  Whether auxiliary trace is in progress (started) or not (stopped). You can start, stop, or pause tracing. Input Press the Clear key and type CEMT INQUIRE AUXTRACE (the minimum abbreviation is CEMT I A). You will get a display that shows the current status. required. ┌─Auxtrace─┐ >>──CEMT Inquire──┴──────────┴──>< Sample panel I A Status. . : Results - overtype to modify Aux Cur(A) Sto Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE AUXTRACE panel Displayed fields Auxiliary identifies this panel as relating to auxiliary trace. Current(A|B) displays a 1-character identifier of the current auxiliary trace file, which in CICS for OS/2 is always set to `A'. Start|Pause|Stop displays the status of auxiliary tracing in your CICS system. The values are: Start Auxiliary tracing is in progress (the auxiliary trace file is open). Pause Auxiliary tracing has stopped, but the trace file has been left open. A subsequent START request causes trace entries to be written immediately following those that were written before the PAUSE request. Stop Auxiliary tracing has stopped, and the trace file is closed. Note: You can reset this value by overtyping it with a different value. ═══ 9.9. CEMT INQUIRE CONNECTION ═══ CEMT INQUIRE CONNECTION Function Retrieve information about system connections. Description CEMT INQUIRE CONNECTION returns information about the status of connections to remote systems. Input Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT INQUIRE CONNECTION (the minimum abbreviation is CEMT I C). You get a display that lists the current status.  Type CEMT INQUIRE CONNECTION (CEMT I C) followed by as many of the other attributes as are necessary to limit the range of information that you require. So, for example, if you enter cemt i c ins acq, the resulting display will show you the details of only those connections that are in service and acquired. >>──CEMT Inquire Connection──┬─(value)─┬──┬────────────────┬──┬────────────┬───> └─ALl─────┘ └─NETName(value)─┘ ├─Inservice──┤ └─OUtservice─┘ >──┬───────────┬──┬─────────┬──>< ├─ACquired──┤ ├─Sna─────┤ ├─Released──┤ ├─Tcpip───┤ ├─OBtaining─┤ ├─NETBios─┤ └─FReeing───┘ └─Xm──────┘ ALL is the default. (value) specifies a name (1-4 characters) defined for an intersystem communication (ISC) connection. Sample panel I C Status. . : Results - overtype to modify Con(CL01) Net(CICSCL01) Ins Acq Net Con(CL02) Net(CICSCL02) Ins Acq Net Con(CL03) Net(CICSCL03) Ins Rel Net Con(CL04) Net(CICSCL04) Ins Acq Net Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE CONNECTION panel Displayed fields Connection(value) identifies this panel as relating to system connections, and displays the 4-character name by which the connection is known. Netname(value) displays the 8-character name by which the remote system is known to the network. Inservice|Outservice displays whether the system can receive and send data. The values are: Inservice The system is in service; that is, it is available for use. Outservice The system is out of service; that is, it is not available for use. Acquired|Released|Obtaining|Freeing displays the state of the connection between CICS and a remote system. The values are: Acquired The connection is acquired. Released The connection is released. Although the connection might be in service, it is not usable. Obtaining The connection is being acquired. The connection remains in the OBTAINING state until all the criteria for ACQUIRED have been met. Freeing The connection is being released. Sna|NetBios|Tcpip|Xm displays the access method in use for this connection. The values are: Sna The connection is used for intersystem communication (ISC), via Communications Server. NetBios The connection is used for ISC or for an IBM CICS Client via NetBios. Tcpip The connection is used for ISC or for an IBM CICS Client via TCP/IP. Xm The connection is used for a local IBM CICS Client system. Appc displays the protocol in use if this is an SNA connection. The only value is: Appc The connection uses the SNA LUTYPE6.2 protocol for intersystem communication. ═══ 9.10. CEMT INQUIRE FILE ═══ CEMT INQUIRE FILE Function Retrieve information about File Manager and remote files. Description The values that are returned to you can vary according to when the command is issued. For example, if the file is closed when you issue the command, much of the information you receive tells you the state of the file when it is next opened. If the file has never been opened, you receive default or null values for some of the options, which could change when the file is opened. Input Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT INQUIRE FILE (the minimum abbreviation is CEMT I F). You get a display that lists the current status.  Type CEMT INQUIRE FILE (CEMT I F) followed by as many of the other attributes as are necessary to limit the range of information that you require. So, for example, if you enter cemt i fi v op en up, the resulting display will show you the details of only those files that are VSAM, open, enabled, and updatable. ┌─ALl─────┐ >>──CEMT Inquire FIle──┴─(value)─┴──┬────────┬──┬────────┬──┬───────────┬──────> ├─Vsam───┤ ├─OPen───┤ ├─ENabled───┤ └─REMote─┘ └─CLosed─┘ ├─UNenabled─┤ └─DIsabled──┘ >──┬────────┬──┬──────────┬──┬───────────┬──┬──────────┬──┬──────────┬─────────> ├─REad───┤ ├─UPdate───┤ ├─ADdable───┤ ├─BRowse───┤ ├─DElete───┤ └─NORead─┘ └─NOUpdate─┘ └─NOAddable─┘ └─NOBrowse─┘ └─NODelete─┘ >──┬────────────┬──┬───────┬──┬───────────────┬──>< ├─EMptyrec───┤ ├─OLd───┤ └─DSname(value)─┘ └─NOEMptyrec─┘ └─Share─┘ ALl is the default. Information about all files is given, unless you specify a selection of files to be queried. (value) specifies a name (1-8 characters) defined in the file control table (FCT). Sample panel I F Status. . : Results - overtype to modify Fil(FAAAEFBU) Vsa Ope Ena Rea Upd Add Bro Del Sha Dsn(DATA\FAAAEFBU.BTR ) Fil(FAAAEFIE) Vsa Ope Ena Rea Upd Add Bro Del Sha Dsn(DATA\FAAAEFIE.BTR ) Fil(FAACTFGR) Vsa Ope Ena Rea Upd Add Bro Del Sha Dsn(DATA\FAACTFTB.BTR ) Fil(FAACTFTB) Vsa Ope Ena Rea Upd Add Bro Del Sha Dsn(DATA\FAACTFTB.BTR ) Fil(FAAHLFT1) Vsa Ope Ena Rea Upd Add Bro Del Sha Dsn(DATA\FAAHLFT1.BTR ) Fil(FAAHLFT2) Vsa Ope Ena Rea Upd Add Bro Del Sha Dsn(DATA\FAAHLFT2.BTR ) Fil(FAAHLFT3) Vsa Ope Ena Rea Upd Add Bro Del Sha Dsn(DATA\FAAHLFT3.BTR ) Fil(FAAMGFMG) Vsa Ope Ena Rea Upd Add Bro Del Sha Dsn(DATA\FAAMGFMG.BTR ) + Fil(FAAMSFSC) Vsa Ope Ena Rea Upd Add Bro Del Sha Dsn(DATA\FAAMSFSC.BTR ) Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE FILE panel Displayed fields File indicates that this panel relates to a file inquiry. (value) displays the name (1-8 characters) defined in the file control table (FCT). Vsam|Remote displays the access method of the file. The values are: Vsam CICS for OS/2 File Manager (VSAM). Remote The file is defined as remote. Open|Closed displays the open status of the file. The values are: Open The file is open. If the file is OPEN ENABLED, it is available for data accesses by CICS transactions. If it is OPEN DISABLED, it must first be enabled before it is available. Closed The file is closed; the access method does not allow accesses to the data until the file is opened. The file can be opened either explicitly by the user or, if the file has the ENABLED attribute, implicitly by CICS on the next reference to the file. A file with the DISABLED attribute can be enabled only by a SET FILE ENABLED command. A file with the UNENABLED attribute can be enabled by a SET FILE ENABLED command or SET FILE OPEN command. Note: You can reset this value by overtyping it with a different value. Enabled|Unenabled|Disabled displays whether transactions can access the file. The values are: Enabled The file is available for use by transactions and, if closed, it is opened on the first request. Unenabled The file is not available for use by transactions except for those that are currently using it. This status is the same as DISABLED except that it occurs implicitly when a SET FILE CLOSE is requested. The file is enabled implicitly by a SET FILE OPEN command. Disabled The file is not available for use by transactions except for those that are currently using it. The file can be reenabled by a SET FILE ENABLED command. (See also UNENABLED.) It is not possible to disable a remote file. Note: You can reset this value by overtyping it with a different value. Read|Noread displays whether you can read records from the file. The values are: Read You can read records in the file. Noread You cannot read records in the file. Update|Noupdate displays whether the file is updatable. The values are: Update You can update records in the file. Noupdate You cannot update records in the file. Addable|Noaddable displays whether new records can be added to the file. The values are: Addable New records can be added to the file. Noaddable New records cannot be added to the file. Browse|Nobrowse displays whether you can browse the file. The values are: Browse You can browse records in the file. Nobrowse You cannot browse records in the file. Delete|Nodelete displays whether you can delete records from the file. The values are: Delete You can delete records from the file. Nodelete You cannot delete records from the file. Emptyreq|Noemptyreq displays whether the file is to be made empty when it is being opened. The values are: Emptyreq Indicates that when a file is being opened, its data is erased. Noemptyreq Indicates that when a file is being opened, its data is not erased. Note: You can reset this value by overtyping it with a different value when setting the file open. Old|Share displays the disposition of this file. The values are: Old The file is unrecoverable. Share The file is recoverable. Dsname(value) displays the name (1-44 characters) of the file on disk. ═══ 9.11. CEMT INQUIRE MODENAME ═══ CEMT INQUIRE MODENAME Function Retrieve information about connection sessions. Description INQUIRE MODENAME returns information about the named group of sessions that has been defined for a connection to a remote system or to another CICS region. Input Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT INQUIRE MODENAME (the minimum abbreviation is CEMT I M). You get a display that lists the current status.  Type CEMT INQUIRE MODENAME (CEMT I M) followed by as many of the other attributes as are necessary to limit the range of information that you require. Mode names need not be unique. A mode name consisting of eight blanks is valid. To specify this name, enclose the string of blanks within single quotation marks: MODENAME(' ') ┌─ALl─────┐ >>──CEMT Inquire MODename──┴─(value)─┴──┬───────────────────┬──────────────────> └─COnnection(value)─┘ >──┬────────────────┬──┬──────────────────┬──┬───────────────┬──>< └─Maximum(value)─┘ └─AVailable(value)─┘ └─ACTive(value)─┘ ALl is the default. (value) specifies the name (1-8 characters) of a group of sessions. Sample panel I M Status. . : Results Mod(LU62PS ) Con(CONJ) Max(008) Ava(008) Act(000) Mod(LU62PS ) Con(JLU2) MAx(008) Ava(008) Act(000) Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE MODENAME panel Displayed fields Note: If the modename has not been defined to Communications Server, a NOT FOUND response is displayed. Modename indicates that this panel relates to a MODENAME inquiry. (value) displays the name (1-8 characters) of a group of sessions. Connection(value) displays the 4-character identifier of the remote system with which this group of ISC sessions is connected. Maximum(value) displays the maximum number of sessions that are supported at one time within this group of sessions, in the range 0-999. Available(value) displays the currently negotiated number of sessions within the group that can be allocated for use at one time. Active(value) displays the number of sessions within the group (or "modename") that are currently in use ("bound"). ═══ 9.12. CEMT INQUIRE NETNAME ═══ CEMT INQUIRE NETNAME Function Retrieve information about a network. Description If you are familiar with network names, you may prefer to use this request as an alternative to CEMT INQUIRE TERMINAL. Input Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT INQUIRE NETNAME (the minimum abbreviation is CEMT I N). You get a display that lists the current status.  Type CEMT INQUIRE NETNAME (CEMT I N) followed by as many of the other attributes as are necessary to limit the range of information that you require. So, for example, if you enter cemt i n ins , the resulting display will show you the details of only those netnames that are in service. You can then tab to the highlighted or blank fields and overtype them with the required values. ┌─ALl─────┐ >>──CEMT Inquire Netname──┴─(value)─┴──┬────────────────────┬──────────────────> └─TRansaction(value)─┘ >──┬─────────────────┬──┬────────────┬──┬───────┬──┬─────────────────┬─────────> └─PRiority(value)─┘ ├─Inservice──┤ ├─ATi───┤ └─TErminal(value)─┘ └─Outservice─┘ └─NOAti─┘ >──┬──────────┬──>< ├─ACquired─┤ └─RELeased─┘ ALl is the default. (value) specifies an 8-character network name. The remaining operands for NETNAME are identical to those for CEMT INQUIRE TERMINAL. Sample panel I N Status. . : Results - overtype to modify Net(CICSCL05) Tra(CEMT) Pri( 000 ) Ins Ati Tti Ter(_02X) Acq Net(CICSP234) Pri( 086 ) Ins Ati Tti Ter(P234) Rel Cre Net(CICSV123) Pri( 086 ) Ins Ati Tti Ter(V123) Acq Cre Net(CICSV124) Pri( 086 ) Ins Ati Tti Ter(V124) Rel Cre Net(CL02C002) Pri( 086 ) Ins Ati Tti Ter(C002) Acq Cre Net(CL05C000) Tra(CEMT) Pri( 086 ) Ins Ati Tti Ter(C000) Acq Cre Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE NETNAME panel Displayed fields Netname indicates that this panel relates to a NETNAME inquiry. (value) displays an 8-character network name. Transaction(value) displays a 4-character string indicating the name of the transaction currently being processed with this terminal as its principal facility or as a secondary facility. Priority(value) displays a 3-character string indicating the priority of this terminal relative to other terminals. The priority of a task is the sum of the transaction priority, the terminal priority, and the operator priority. Priority has no meaning for terminals that are ISC sessions being used as alternative facilities. The value is in the range 0-255, where 255 is the highest priority. Note: You can reset this value by overtyping it with a different value. Inservice|Outservice displays whether the terminal is available for use. The values are: Inservice The terminal is available for use. Outservice The terminal is not available for use. Setting a terminal OUTSERVICE means that the terminal can no longer be used by transactions. If PURGE or FORCEPURGE is also specified, any transaction using the terminal is terminated abnormally. If PURGE or FORCEPURGE is not specified, the transaction is allowed to terminate normally, but no further transactions are allowed to use the terminal. Note: You can reset this value by overtyping it with a different value. Ati|Noati displays whether the terminal is available for use by transactions that are automatically initiated from within CICS. The values are: Ati The terminal is available for use. Noati The terminal is not available for use. Note: Because this is a `negative' attribute, the field appears blank. You can, however, tab to this field and overtype it with a different value. Note: A terminal cannot be defined with both NOATI and NOTTI. Tti|Notti displays whether the terminal can be used by the transactions that are initiated from this terminal. The values are: Tti This terminal can be used by transactions. Notti This terminal cannot be used by transactions. Note: Because this is a `negative' attribute, the field appears blank. Purge|Forcepurge displays whether the transactions running with the named terminal can be purged. The values are: Purge Transactions can be terminated only if system and data integrity can be maintained. Forcepurge Transactions are to be purged immediately. This can lead to unpredictable results and should be used only in exceptional circumstances. Terminal(value) displays a 4-character terminal identifier (1-4 characters) as specified in an installed terminal definition. Acquired|Released displays whether CICS is in session with the logical unit represented by this terminal. The values are: Acquired CICS is in session with the logical unit represented by the terminal. Released CICS is not in session with the logical unit represented by the terminal. If you set this option to RELEASED, a session is terminated immediately if you also specify the PURGE option, otherwise the session is terminated when the current active transaction finishes. Note: You can reset this value by overtyping it with a different value. Create|Nocreate displays whether the terminal can be acquired automatically by ATI transactions. The values are: Create If the terminal is not in session, CICS acquires it if it is needed to satisfy an ATI request. Nocreate If the terminal is not in session, CICS does not acquire it to satisfy an ATI request. A session must be started by, for example, a logon request or a CEMT SET TERMINAL ACQUIRED command before the ATI request can be satisfied. Note: Because this is a `negative' attribute, the field appears blank. ═══ 9.13. CEMT INQUIRE PROGRAM ═══ CEMT INQUIRE PROGRAM Function Retrieve information about programs Description INQUIRE PROGRAM returns information about the programs that are defined to your system. Only programs that have been defined in the CICS system definition (FAACTFTB) file or that have been autoinstalled on the running CICS system are accessible through CEMT. Input Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT INQUIRE PROGRAM (the minimum abbreviation is CEMT I P ). You get a display that lists the current status.  Type CEMT INQUIRE PROGRAM (CEMT I P ) followed by as many of the other attributes as are necessary to limit the range of information that you require. So, for example, if you enter cemt i prog c e, the resulting display will show you the details of only those programs that are written in C language and are enabled. ┌─ALl─────┐ >>──CEMT Inquire Program──┴─(value)─┴──┬───────┬──┬──────────┬──┬────────┬─────> ├─PLi───┤ ├─Enabled──┤ ├─CEDf───┤ ├─CObol─┤ └─DIsabled─┘ └─NOcedf─┘ └─C─────┘ >──┬─────────────────┬──┬─────────────────┬──┬─────────────────────┬──>< └─REScount(value)─┘ └─USecount(value)─┘ └─REMotesystem(value)─┘ ALl is the default. (value) is a program identifier (1-8 characters), which is the name of a specific program entry in the table of installed program definitions. If you omit the program name, the ALL option is assumed by default. Sample panel INQUIRE PROGRAM Status. . : Results - overtype to modify Prog(FAAAEPDL) Cob Pro Ena Sha Res(000) Use(0000005) Any Cex Ful Prog(FAAAEPMN) Cob Pro Ena Sha Res(000) Use(0000008) Any Cex Ful Prog(FAAATPCI) Cob Pro Ena Sha Res(001) Use(0000010) Any Cex Ful Prog(FAAATSSH) Pro Ena Sha Res(000) Use(0000000) Any Cex Ful Prog(FAAATSTR) Pro Ena Sha Res(000) Use(0000000) Any Cex Ful Prog(FAACTPCM) Cob Pro Ena Sha Res(000) Use(0000021) Any Cex Ful Prog(FAACTPCN) Cob Pro Ena Sha Res(000) Use(0000019) Any Cex Ful Prog(FAACTPDC) Cob Pro Ena Sha Res(000) Use(0000006) Any Cex Ful + Prog(FAACTPED) Cob Pro Ena Sha Res(000) Use(0000070) Any Cex Ful Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 15:52:59 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE PROGRAM panel Displayed fields Program indicates that this panel relates to a PROGRAM inquiry. (value) displays an 8-character program identifier (1-8 characters), which is the name of a specific program entry in the table of installed program definitions. Length(value) displays the size of the program in bytes for a data (.DAT) module. Pli|Cobol|C displays the language in which the program is written. The values are: PL/I, COBOL, or C Supported languages. Program displays the type of program. The values are: Program The entry is defined in the CICS system definition as a program or has been autoinstalled. Enabled|Disabled displays whether the program is available for use. The values are: Enabled The program is available for use. Disabled The program is not available for use. Note: Programs beginning with "FAA" cannot be disabled because these characters are reserved for use by CICS. Note: You can reset this value by overtyping it with a different value.:enote. Shared|Private displays whether the program is shared or private. The value for all CICS for OS/2 programs is Shared. Cedf|Nocedf displays what action the execution diagnostic facility (EDF) is to take for this program when the program runs under EDF. The values are: Cedf EDF diagnostic panels are displayed. If the program was translated with the EDF option, all EDF panels are displayed. If it was translated with NOEDF, no EDF panels are displayed. Nocedf All CEDF activities, including initiation and termination panels, stop while this program is being processed, and no panels are displayed. Rescount(value) displays a 3-character string identifying the number of separate invocations of this program that are taking place at the time of this inquiry. Usecount(value) displays a 6-character string identifying the total number of times the program has been executed since the start of the current CICS session. Any|Below displays whether the program is able to accept data addresses higher than 16MB. CICS for OS/2 always returns a value of Any. Cexeckey|Uexeckey displays which access key the program is executing in. CICS for OS/2 always returns a value of CEXeckey. Dplsubset|Fullapi displays whether the program is restricted to the API subset as for a distributed program link request. The values are: Dplsubset The program is restricted to the DPL API subset, as for a distributed program link request, when it runs in the local CICS region. A program is always restricted to the DPL subset when it is invoked in a remote region via a DPL request, even if this option is not specified. Fullapi The program is not restricted to the DPL subset of the CICS API when it runs in the local CICS region, and can use the full API. A program is always restricted to the DPL subset when it is invoked in a remote region via a DPL request, regardless of this option. Note: CICS for OS/2 always returns a value of Fullapi. Remotesystem(value) displays the 4-character name of the remote system in which the program is to execute. ═══ 9.14. CEMT INQUIRE SYSTEM ═══ CEMT INQUIRE SYSTEM Function Retrieve information about CICS. Input Press the Clear key to clear the screen. Type CEMT INQUIRE SYSTEM (the minimum abbreviation is CEMT I S) to get a display that lists the current system status. Alternatively, if you type simply CEMT INQUIRE (CEMT I), you get the resources panel displayed with the SYSTEM option highlighted. Press enter at this point to see the current system status display. ┌─SYStem─┐ >>──CEMT Inquire──┴────────┴──>< Sample panel I S Status. . : Results - overtype to modify CDsasize( 0147980288 ) SOsstatus( NOTSOS ) CMdprotect( NOCMDPROT ) SToreprotect( ACTIVE ) DFltremsys( ) TIme( 0003000 ) DSalimit( 0147980288 ) TRanisolate( ACTIVE ) ECdsasize( 0147980288 ) UDsasize( 0147980288 ) EDsalimit( 0147980288 ) ERdsasize( 0147980288 ) ESdsasize( 0286064640 ) EUdsasize( 0147980288 ) Maxtasks( 006 ) OPRel( 21 ) OPSys( P ) Progautoinst( AUTOACTIVE ) RDsasize( 0147980288 ) REEntprotect( REENTPROT ) RELease( 0300 ) SCandelay( 3000 ) SDsasize( 0286064640 ) Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE SYSTEM panel Displayed fields CDsasize(value) displays the size, in bytes, of the CICS dynamic storage area (CDSA). CMdprotect(value) displays whether command protection, which validates start addresses passed on in CICS commands, is active or not (that is, whether the CMDPROT system initialization parameter specifies YES or NO). The values are: CMDPROT Command protection is active. CICS checks to ensure that the task itself has write access to the storage referenced on the command before writing to the storage on the task's behalf. NOCMDPROT Command protection is not active. CICS does not check to ensure that the task itself has write access to the storage referenced on the command before writing to the storage on the task's behalf. DFltremsys(value) displays the name of the default remote system, to which transaction requests will be routed if not recognized at the local system. Note: You can reset this value by overtyping it with a different value. DSalimit(value) displays the maximum amount of storage available to CICS. ECdsasize(value) displays the size, in bytes, of the extended CICS dynamic storage area. EDsalimit(value) displays the maximum amount of storage available to CICS. ERdsasize(value) displays the size, in bytes, of the extended read-only dynamic storage area. ESdsasize(value) displays the current size of the extended shared dynamic storage area (ESDSA). EUdsasize(value) displays the size, in bytes, of the extended user dynamic storage area (EUDSA). MAxtasks(value) displays the maximum number of tasks, both active and suspended, allowed at any one time in the CICS system. OPRel(value) displays the formal release number of the operating system currently running. For example, OS/2 Warp Version 3 is represented by 23. OPSys(value) displays the type of operating system currently running. A value of "P" represents OS/2. PROGAUTOInst displays whether autoinstall for programs is active or inactive. The values are: AUTOACTIVE Autoinstall for programs is active. On first use, if a program is not defined, the definition is created dynamically. RDsasize(value) displays the current size of the read-only dynamic storage area (RDSA). REEntprotect(value) displays whether read-only storage is in use for reentrant programs. The values are: REENTPROTECT All CICS for OS/2 programs have read-only storage. RELease(value) displays the level of the CICS code present. This is a 4-digit number representing the CICS version and release numbers. For example, CICS for OS/2 Version 3.0 has the value ( 0300 ). SCandelay(value) displays the maximum number of milliseconds between the receipt of a terminal request, and the time when CICS begins to process the request. Note: This is the value specified in the MAXWAIT parameter of CONFIG.SYS. SDsasize(value) displays the current size of the shared dynamic storage area (SDSA). SOSStatus(value) displays whether CICS is short on storage. The values returned are: NOTSOS CICS is not short on storage. SOS CICS is short of storage. SToreprotect(value) displays whether storage protection is active in the CICS region. The values returned are: ACTIVE CICS is operating with storage protection. TIme(value) displays the interval, in milliseconds, for which CICS releases control to the operating system if no transactions are ready to resume processing. Note: This is the value specified in the MAXWAIT parameter of CONFIG.SYS. TRanisolate displays the status of transaction isolation. The values returned are: ACTIVE Transaction isolation is active in the CICS region. Udsasize(value) displays the size, in bytes, of the user dynamic storage area (UDSA). Note: All dynamic storage area sizes are obtained from OS/2 using the DosQuerySysInfo function. ═══ 9.15. CEMT INQUIRE TASK ═══ CEMT INQUIRE TASK Function Retrieve information about a user task. Description INQUIRE TASK returns information about user tasks. Only information about user tasks can be displayed or changed; information about CICS-generated system tasks or subtasks cannot be displayed or changed. System tasks are those tasks started (and used internally) by CICS, and not as a result of a user transaction. Input Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT INQUIRE TASK (the minimum abbreviation is CEMT I TA). You get a display that lists the current status.  Type CEMT INQUIRE TASK (CEMT I TA) followed by as many of the other attributes as are necessary to limit the range of information that you require. So, for example, if you enter cemt i ta ru , the resulting display will show you the details of only those tasks that are running. ┌─All─────┐ >>──CEMT Inquire TAsk──┴─(value)─┴──┬───────────────┬──┬─────────────────┬─────> └─TRANid(value)─┘ └─FACility(value)─┘ >──┬──────────────┬──┬──────┬──┬─────────────────┬──>< ├─RUnning──────┤ ├─TAsk─┤ └─PRiority(value)─┘ ├─DIspatchable─┤ ├─TErm─┤ └─SUspended────┘ └─DEst─┘ All is the default. (value) is the CICS-generated task number, in the range 1-9999999. You cannot use the symbols * and + to specify a family of tasks. Sample panel I TA Status. . : Results - overtype to modify Tas(0000292) Tra(CEMT) Fac(C000) Run Ter Pri( 255 ) Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE TASK panel Displayed fields Task indicates that this panel relates to a TASK inquiry. (value) displays a CICS-generated task number in the range 1-9999999. Tranid(value) displays a 4-character string identifying the transaction name associated with the task. Facility(value) displays a 4-character string identifying the name of the terminal or queue that initiated the task. If no FACILITY value is displayed, the task was started without a facility. Running|Dispatchable|Suspended displays the status of this task. The values are: Running The task is running. Dispatchable The task is dispatchable. Suspended The task is suspended. Task|Term|Dest displays the type of facility that initiated this task. The values are: Task The task was initiated from another task. Term The task was initiated from a terminal. Dest The task was initiated by a destination trigger level as defined in the destination control table (DCT). Priority(value) displays the priority of the task, in the range 0-255 where 255 is the highest priority. Note: You can reset this value by overtyping it with a different value. Purge|Forcepurge is an input field for purging or forcepurging a task. The values are: Purge The task is to be terminated. Termination occurs only when system and data integrity can be maintained. Forcepurge The task is to be terminated immediately. System integrity is not guaranteed. In some extreme cases CICS terminates abnormally. If you want to terminate a task but do not want to terminate CICS, you should use PURGE instead of FORCEPURGE. ═══ 9.16. CEMT INQUIRE TCLASS ═══ CEMT INQUIRE TCLASS Function Retrieve information about tasks within a task class. Description INQUIRE TCLASS returns information about the current and maximum number of tasks. Input Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT INQUIRE TCLASS (the minimum abbreviation is CEMT I TC). You get a display that lists the current status.  Type CEMT INQUIRE TCLASS (CEMT I TC) followed by as many of the other attributes as are necessary to limit the range of information that you require. So, for example, if you enter cemt i tc (01), the resulting display will show only the information relating to class 01. ┌─ALL─────┐ >>──CEMT Inquire TClass──┴─(value)─┴──┬──────────────────┬─────────────────────> └─Maxactive(value)─┘ >──┬────────────────┬──>< └─Current(value)─┘ ALL is the default. (value) is the 2-digit transaction class id. Sample panel I TC Status. . : Results - overtype to modify Tcl(01) Max( 001 ) Cur(000) Tcl(02) Max( 001 ) Cur(000) Tcl(03) Max( 001 ) Cur(000) Tcl(04) Max( 001 ) Cur(000) Tcl(05) Max( 001 ) Cur(000) Tcl(06) Max( 001 ) Cur(000) Tcl(07) Max( 001 ) Cur(000) Tcl(08) Max( 001 ) Cur(000) Tcl(09) Max( 001 ) Cur(000) Tcl(10) Max( 001 ) Cur(000) Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE TCLASS panel Displayed fields Tclass indicates that this panel relates to a TCLASS inquiry. (value) displays the 2-digit transaction class id. Maxactive(value) displays the largest number of transactions in the transaction class which are allowed to run concurrently. The value can be in the range 0-99. Note: You can reset this value by overtyping it with a different value. Values greater than 99 are truncated. Current(value) displays the total number of transactions that are currently active or queued in the transaction class. You cannot use the symbols * and + to specify a family of tasks. ═══ 9.17. CEMT INQUIRE TDQUEUE ═══ CEMT INQUIRE TDQUEUE Function Retrieve information about transient data queues. Description INQUIRE TDQUEUE returns information about a named transient data queue that is defined in the destination control table (DCT). Input Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT INQUIRE TDQUEUE (the minimum abbreviation is CEMT I TD). You get a display that lists the current status.  Type CEMT INQUIRE TDQUEUE (CEMT I TD) followed by as many of the other attributes as are necessary to limit the range of information that you require. So, for example, if you enter cemt i td ind en, the resulting display will show you the details of only those transient data queues that are indirect and enabled. ┌─ALL─────┐ >>──CEMT Inquire TDqueue──┴─(value)─┴──┬─────────────────────┬──┬──────────┬───> └─TRIggerlevel(value)─┘ ├─INDirect─┤ ├─EXtra────┤ ├─INTra────┤ └─Remote───┘ >──┬────────────────┬──┬──────────┬──┬────────┬──┬───────────────┬─────────────> └─Nameind(value)─┘ ├─ENabled──┤ ├─Open───┤ └─TErmid(value)─┘ └─Disabled─┘ └─Closed─┘ >──┬───────────────┬──>< └─TRAnid(value)─┘ ALL is the default. (value) is the identifier (1-4 characters) of a transient data queue. Sample panel I TD Status. . : Results - overtype to modify Tdq(CAEX) Ena Ope Ext Tdq(CCBL) Tri( 00000 ) Ena Int Tdq(CPLD) Tri( 00000 ) Ena Int Tdq(CPLI) Tri( 00000 ) Ena Int Tdq(CSCS) Tri( 00000 ) Ena Int Tdq(CSMT) Tri( 00000 ) Ena Int Tdq(L860) Tri( 00003 ) Ena Ter(L860) Tra(OREQ) Int Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE TDQUEUE panel Displayed fields Tdqueue indicates that this panel relates to a TDQUEUE inquiry. (value) displays the 4-character identifier of a transient data queue. Queue names beginning with "C" are normally reserved for use by CICS. Triggerlevel(value) (intrapartition queues only) displays the number of requests for output to a queue that must accrue before automatic transaction initiation (ATI) occurs. Note: You can reset this value by overtyping it with a different value. The number can be between 0 and 32767. Indirect|Extra|Intra|Remote displays the type of this transient data queue. The values are: Indirect The queue type is indirect. The name of the final target queue is shown in the next field. Extra The queue type is extrapartition. Intra The queue type is intrapartition. Remote The queue type is remote. The name of the remote system is displayed in the next field. Nameind(value) (indirect queues only) displays a 4-character string identifying the name of the queue pointed to by the indirect queue. Remote(value) (remote queues only) displays the name of the remote system in which the queue resides. Enabled|Disabled (all except indirect queues) displays a value indicating whether the queue can be accessed by applications. The values are: Enabled The queue can be accessed by applications. Disabled The queue cannot be accessed by applications, although it can still be open. Queues with names beginning with "C" cannot be disabled because they are usually reserved for use by CICS. Note: You can reset this value by overtyping it with a different value. Open|Closed (extrapartition queues only) displays whether the extrapartition queue is open or closed. The values are: Open The queue is open. Closed The queue is closed. Note: You can reset this value by overtyping it with a different value. Termid(value) displays the 4-character name of the terminal or session to be associated with this queue when automatic transaction initiation occurs. See also Tranid and Triggerlevel. Tranid(value) displays the 4-character identifier of the transaction that is to be initiated automatically when the queue trigger level is reached. ═══ 9.18. CEMT INQUIRE TERMINAL ═══ CEMT INQUIRE TERMINAL Function Retrieve information about terminals. Description INQUIRE TERMINAL returns information about a named terminal defined in the terminal control table (TCT) or which has been autoinstalled. If you are familiar with network names, you may prefer to use the command that uses these names. See CEMT INQUIRE NETNAME. Input Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT INQUIRE TERMINAL (the minimum abbreviation is CEMT I TE). You get a display that lists the current status.  Type CEMT INQUIRE TERMINAL (CEMT I TE) followed by as many of the other attributes as are necessary to limit the range of information that you require. So, for example, if you enter cemt i te i acq, the resulting display will show you the details of only those terminals that are in service and available for use. ┌─ALl─────┐ >>──CEMT Inquire TErminal──┴─(value)─┴──┬────────────────────┬─────────────────> └─TRansaction(value)─┘ >──┬─────────────────┬──┬────────────┬──┬───────┬──┬────────────────┬──────────> └─PRiority(value)─┘ ├─Inservice──┤ ├─ATi───┤ └─NEtname(value)─┘ └─Outservice─┘ └─NOAti─┘ >──┬──────────┬──>< ├─ACquired─┤ └─RELeased─┘ ALl is the default. (value) is a terminal identifier (1-4 characters) as specified in an installed terminal definition. If the terminal name is, for example, S201, this option is coded thus: CEMT INQUIRE TERMINAL(S201) Sample panel I TE Status. . : Results - overtype to modify Ter(C000) Tra(CEMT) Pri( 086 ) Ins Ati Tti Net(CL05C000) Acq Cre Ter(C002) Pri( 086 ) Ins Ati Tti Net(CL02C002) Acq Cre Ter(P234) Pri( 086 ) Ins Ati Tti Net(CICSP234) Rel Cre Ter(V123) Pri( 086 ) Ins Ati Tti Net(CICSV123) Acq Cre Ter(V124) Pri( 086 ) Ins Ati Tti Net(CICSV124) Rel Cre Ter(_02X) Tra(CEMT) Pri( 000 ) Ins Ati Tti Net(CICSCL05) Acq Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE TERMINAL panel Displayed fields Terminal indicates that this panel relates to a TERMINAL inquiry. (value) displays a 4-character terminal identifier as defined in an installed terminal definition. This includes all terminals and sessions, but not model TCTTEs, mode groups, or system entries. See also Netname. Transaction(value) displays a 4-character string identifying the name of the transaction currently being processed with this terminal as its principal facility or as a secondary facility. Priority(value) displays a 3-character string identifying the priority of a terminal relative to other terminals. The priority of a task is the sum of the transaction priority, the terminal priority, and the operator priority. Priority has no meaning for terminals that are ISC sessions being used as alternative facilities. Note: You can reset this value by overtyping it with a different value. The value is in the range 0-255, where 255 is the highest priority. Inservice|Outservice displays whether the terminal is available for use. The values are: Inservice The terminal is available for use. Outservice The terminal is not available for use. Setting a terminal Out(service) means that the terminal can no longer be used by transactions. If PURGE or FORCEPURGE is also specified, any transaction using the terminal is terminated abnormally. If PURGE or FORCEPURGE is not specified, the transaction is allowed to terminate normally, but no further transactions are allowed to use the terminal. Note: You can reset this value by overtyping it with a different value. Ati|Noati displays whether the terminal is available for use by transactions that are automatically initiated from within CICS. Ati The terminal is available for use. Noati The terminal is not available for use. Note: Because this is a `negative' attribute, the field appears blank. You can, however, tab to this field and overtype it with a different value. Note: 1. You can reset this value by overtyping it with a different value. 2. A terminal cannot be defined with both NOATI and NOTTI. Tti|Notti displays whether the terminal can be used by the transactions that are initiated from this terminal. The values are: Tti This terminal can be used by transactions. Notti This terminal cannot be used by transactions. Note: Because this is a `negative' attribute, the field appears blank. Purge|Forcepurge is an input field that allows you to purge transactions running with the named terminal. The values are: Purge Transactions will be terminated only if system and data integrity can be maintained. Forcepurge Transactions are to be purged immediately. This can lead to unpredictable results and should be used only in exceptional circumstances. Netname(value) displays an 8-character network name. Acquired|Released displays whether CICS is in session with the logical unit represented by this terminal. The values are: Acquired CICS is in session with the logical unit represented by the terminal. Released CICS is not in session with the logical unit represented by the terminal. If you set this option to RELEASED, a session is terminated immediately if you also specify the PURGE option, otherwise the session is terminated when the current active transaction finishes. Note: You can reset this value by overtyping it with a different value. Create|Nocreate displays whether the terminal can be acquired automatically by ATI transactions. The values are: Create If the terminal is not in session, CICS acquires it if it is needed to satisfy an ATI request. Nocreate If the terminal is not in session, CICS does not acquire it to satisfy an ATI request. A session must be started by, for example, a logon request or a CEMT SET TERMINAL ACQUIRED command before the ATI request can be satisfied. ═══ 9.19. CEMT INQUIRE TRANSACTION ═══ CEMT INQUIRE TRANSACTION Function Retrieve information about transactions. Description INQUIRE TRANSACTION returns information about a selected transaction. Input Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT INQUIRE TRANSACTION (the minimum abbreviation is CEMT I TR). You get a display that lists the current status.  Type CEMT INQUIRE TRANSACTION (CEMT I TR) followed by as many of the other attributes as are necessary to limit the range of information that you require. So, for example, if you enter cemt i trans en pu, the resulting display will show you the details of only those transactions that are enabled and purgeable. ┌─ALL─────┐ >>──CEMT Inquire TRANSaction──┴─(value)─┴──┬─────────────────┬─────────────────> └─PRIority(value)─┘ >──┬────────────────┬──┬───────────────┬──┬──────────┬──┬──────────────┬──>< └─PROgram(value)─┘ └─TClass(value)─┘ ├─Enabled──┤ ├─PUrgeable────┤ └─Disabled─┘ └─NOTpurgeable─┘ ALL is the default. (value) is a 1-4 character transaction identifier. Only transactions that have been defined in the CICS system definition (CSD) file and installed on the running CICS system are accessible through CEMT. Sample panel I TR Status. . : Results - overtype to modify Tra(CADL) Pri( 000 ) Pro(FAAAEPDL) Tcl( 00 ) Ena Pur Tra(CAEX) Pri( 000 ) Pro(FAAAEPMN) Tcl( 00 ) Ena Pur Tra(CAIM) Pri( 000 ) Pro(FAAAEPMN) Tcl( 00 ) Ena Pur Tra(CCIN) Pri( 000 ) Pro(FAATPPCI) Tcl( 00 ) Ena Pur Tra(CEBR) Pri( 000 ) Pro(FAACEBR ) Tcl( 00 ) Ena Pur Tra(CECI) Pri( 000 ) Pro(FAAATPCI) Tcl( 00 ) Ena Pur Tra(CED1) Pri( 000 ) Pro(FAAATPML) Tcl( 00 ) Ena Pur Tra(CEDA) Pri( 000 ) Pro(FAACTPED) Tcl( 00 ) Ena Pur Tra(CEDF) Pri( 000 ) Pro(FAAATPDF) Tcl( 00 ) Ena Pur Tra(CEMT) Pri( 255 ) Pro(FAAMTPCL) Tcl( 00 ) Ena Tra(CEPN) Pri( 000 ) Pro(FAAPNPPN) Tcl( 00 ) Ena Pur Tra(CESF) Pri( 000 ) Pro(FAALSPSF) Tcl( 00 ) Ena Pur Tra(CESN) Pri( 000 ) Pro(FAALSPSN) Tcl( 00 ) Ena Pur Tra(CETR) Pri( 000 ) Pro(FAACTPTA) Tcl( 00 ) Ena Pur Tra(CHLP) Pri( 000 ) Pro(FAAHLPON) Tcl( 00 ) Ena Pur Tra(CLOG) Pri( 000 ) Pro(FAALSPDL) Tcl( 00 ) Ena Pur Tra(CMLV) Pri( 000 ) Pro(FAAOIPLV) Tcl( 00 ) Ena Pur + Tra(CPMI) Pri( 086 ) Pro(FAAMIR ) Tcl( 00 ) Ena Pur Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE TRANSACTION panel Displayed fields Transaction indicates that this panel relates to a TRANSACTION inquiry. (value) displays a 4-character transaction identifier. Only transactions that have been defined in the CICS system definition (CSD) file and installed on the running CICS system are accessible through CEMT. Priority(value) displays a value indicating the priority of a transaction relative to other transactions. When a transaction is running as a CICS task, the priority of a task is the sum of the transaction priority, the terminal priority, and the operator priority. Note: You can reset this value by overtyping it with a different value. The value is in the range 0-255, where 255 is the highest priority. Program(value) displays an 8-character string identifying the name of the first program to be executed when this transaction is started. Tclass(value) displays a 2-digit string identifying the name of the transaction class to which the transaction belongs. If the transaction does not belong to a class, 00 is returned. Note: You can reset this value by overtyping it with a different value. Enabled|Disabled displays whether the transaction is available for use. The values are: Enabled The transaction is available for use. Disabled The transaction is not available for use. Note: If a transaction is disabled, this does not prevent a START command that names this transaction from being shipped to a remote region. When a task is attached for the requested transaction, CICS checks that the transaction is enabled in the remote region. Note: You can reset this value by overtyping it with a different value. Purgeable|Notpurgeable displays whether the transaction is purgeable in system stall conditions. The values are: Purgeable The transaction is purgeable. Notpurgeable The transaction cannot be purged. Note: Because this is a `negative' attribute, the field appears blank. You can, however, tab to this field and overtype it with a different value. Note: You can reset this value by overtyping it with a different value. ═══ 9.20. CEMT INQUIRE TSQUEUE ═══ CEMT INQUIRE TSQUEUE Function Retrieve information about temporary storage queues. Description The INQUIRE TSQUEUE command returns information about temporary storage queues (TS queues). The INQUIRE TSQUEUE command operates on all the temporary storage queues that exist in the CICS region, including those created internally by CICS for use by CICS itself. You can identify the temporary storage queues created by CICS for its own use by queue names that begin with the following character strings: X'FA' to X'FF' CICS CEBR Default CEBR queue name DF CICS DFxxxx CICS REQIDS (where x is hexadecimal) Input Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT INQUIRE TSQUEUE (the minimum abbreviation is CEMT I TS). You get a display that lists the current status.  Type CEMT INQUIRE TSQUEUE (CEMT I TS) followed by as many of the other attributes as are necessary to limit the range of information that you require. So, for example, if you enter cemt i ts main, the resulting display will show you the details of only those temporary storage queues that are resident in main storage. ┌─All─────┐ >>──CEMT Inquire TSqueue──┴─(value)─┴──┬─────────────────┬─────────────────────> └─Numitems(value)─┘ >──┬────────────────┬──┬───────────┬──┬───────────────────┬────────────────────> └─Flength(value)─┘ ├─Auxiliary─┤ └─MAxitemlen(value)─┘ └─Main──────┘ >──┬───────────────────┬──┬─────────────────┬──>< └─MInitemlen(value)─┘ └─Xtsqueue(value)─┘ All is the default. (value) is the name of the temporary storage queue for which information is requested. Sample panel I TS Status. . : Results Tsq(CEBRS209) Num(00002) Fle(00000008) Aux Max(00004) Min(00004) Xts(4345425253323039) Tsq(CEDAV123) Num(00001) Fle(00000064) Aux Max(00064) Min(00064) Xts(4345444156313233) Tsq(CETRC000) Num(00001) Fle(00000056) Aux Max(00056) Min(00056) Xts(4345545243303030) Tsq(CETRV123) Num(00001) Fle(00000056) Aux Max(00056) Min(00056) Xts(4345545256313233) Tsq(CXSNC000) Num(00001) Fle(00001276) Aux Max(01276) Min(01276) Xts(4358534E43303030) Sysid= CICS Applid= CHUCK Response. . : Normal Time . : 16:28:45 Date . : 01/15/96 PF 1 Help 3 End 7 Backward 8 Forward 9 Messages 12 Cancel CEMT INQUIRE TSQUEUE panel Displayed fields Tsqueue indicates that this panel relates to a TSQUEUE inquiry. (value) displays the 8-character name of a temporary storage queue. Numitems(value) displays the number of items in the temporary storage queue. Flength(value) displays the total length in bytes of all the items in the temporary storage queue. Auxiliary|Main displays whether the temporary storage queue is held in temporary or main storage. The values are: Auxiliary The queue is held in either the CICS temporary storage file FAATSFP1 (protected) or FAATSFU1 (unprotected). Main The queue is held in CICS main storage. Maxitemlen(value) displays the length in bytes of the largest item in the temporary storage queue. Minitemlen(value) displays the length in bytes of the smallest item in the temporary storage queue. Xtsqueue(value) displays the name of the temporary storage queue in hexadecimal representation. ═══ 9.21. CEMT PERFORM SHUTDOWN ═══ CEMT PERFORM SHUTDOWN Function Shut down the CICS region. The shutdown can be either controlled or immediate. Syntax >>──CEMT Perform SHUTdown──┬───────────┬──>< └─Immediate─┘ Options Immediate specifies that the system is shut down immediately, terminating all active tasks and ISC sessions. If IMMEDIATE is not specified, all tasks are allowed to finish, and ISC sessions are allowed to terminate normally. ═══ 9.22. CEMT SET AUXTRACE ═══ CEMT SET AUXTRACE Function Change auxiliary tracing options. Description For more information about traces, see the CICS for OS/2 Installation book. See also the description of the CETR transaction in Setting up trace-CETR transaction. Syntax Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT SET AUXTRACE (the minimum abbreviation is CEMT S A). You get a display that lists the current status, similar to that obtained by CEMT INQUIRE AUXTRACE. You can then tab to the highlighted or blank fields and overtype them with the required values.  Type CEMT SET AUXTRACE (CEMT S A) followed by one or more attribute settings that you wish to change. For example, cemt s aux sto will stop auxiliary tracing. >>──CEMT Set Auxtrace──┬───────┬──>< ├─STArt─┤ ├─Pause─┤ └─STOp──┘ Options STArt|Pause|STOp specifies the status of auxiliary tracing in your CICS system. The values are: STArt CICS is to start auxiliary tracing and open the auxiliary trace file if it is currently closed. Pause Auxiliary tracing is to stop, but the file is to remain open. A subsequent START request causes trace entries to be written immediately following those that were written before the PAUSE request. STOp CICS is to stop auxiliary tracing and close the auxiliary trace file. A subsequent START request causes new trace entries to be written at the start of the data set, thereby overwriting the trace entries that were written before the STOP request. ═══ 9.23. CEMT SET CONNECTION ═══ CEMT SET CONNECTION Function Change the status of connections linked to specific terminals. Description Syntax Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT SET CONNECTION (the minimum abbreviation is CEMT S C) followed by one or more connection identifiers or ALL. You get a display that lists the current status, similar to that obtained by CEMT INQUIRE CONNECTION. You can then tab to the highlighted or blank fields and overtype them with the required values.  Type CEMT SET CONNECTION (CEMT S C) followed by one or more connection identifiers or ALL, followed in turn by one or more attribute settings that you wish to change. For example, cemt s c al i will reset the values for all connections to make them available for use (inservice). >>──CEMT Set Connection──┬─(value)─┬──┬────────────┬──┬──────────┬─────────────> └─ALl─────┘ ├─Inservice──┤ ├─ACquired─┤ └─OUtservice─┘ └─Released─┘ >──┬────────────┬──>< ├─PUrge──────┤ └─FOrcepurge─┘ Options (value)|ALl specifies whether the SET command is to apply to one or more connections, or whether it is to apply to all connections. The values are: (value) One or more names (1-4 characters) defined an intersystem communication (ISC) connection. ALl Any changes you request are made to all resources of the specified type that you are authorized to access. Inservice|OUtservice specifies whether the system can receive and send data. The values are: Inservice The system is in service; that is, it is available for use. ACquired|Released specifies whether CICS is to acquire or release a session with the logical unit represented by the CONNECTION name. The values are: ACquired The session is to be acquired. Released The connection is to be released. PUrge|FOrcepurge specifies how associated transactions are to be purged. The values are: PUrge Transactions running on the connected system are abnormally terminated. Transactions are terminated only if system and data integrity can be maintained. FOrcepurge All transactions running on sessions on the connected system are immediately terminated abnormally. This can lead to unpredictable results and should be used only in exceptional circumstances. In some extreme cases (for example, if an error occurs during backout processing), CICS might terminate abnormally. ═══ 9.24. CEMT SET FILE ═══ CEMT SET FILE Function Change some of the attributes of one or more File Manager files. Syntax Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT SET FILE (the minimum abbreviation is CEMT S F) with either a value corresponding to a file name or ALL. You get a display that lists the current status, similar to that obtained by CEMT INQUIRE FILE. You can then tab to the highlighted or blank fields and overtype them with the required values.  Type CEMT SET FILE (CEMT S F) with either the name of a file or ALL, followed by one or more attribute settings that you wish to change. For example, cemt s fi al op will set all files open. >>──CEMT Set File──┬─(value)─┬──┬────────┬──┬──────────┬──┬────────────┬──>< └─ALl─────┘ ├─OPen───┤ ├─ENabled──┤ ├─EMptyrec───┤ └─CLosed─┘ └─DIsabled─┘ └─NOEMptyrec─┘ Options (value)|ALl specifies attributes are to be changed for one or more names defined in the FCT, or for all files. The values are: (value) A name (1-8 characters) defined in the file control table (FCT). ALl Any change you request is made to all files that you are authorized to access. OPen|CLosed specifies the status of the file. The values are: OPen The file is open. If the file is OPEN ENABLED, it is available for data accesses by CICS transactions. If it is OPEN DISABLED, it must first be enabled before it is available. If the file was unenabled by a previous SET FILE CLOSED command, the SET FILE OPEN command reenables the file implicitly. CLosed The file is closed; the access method does not allow accesses to the data until the file is opened. The file can be opened either explicitly by the user or, if the file has the ENABLED attribute, implicitly by CICS on the next reference to the file. When the SET FILE CLOSED command is used, the file is closed and also disabled. (The file is disabled to prevent access requests from implicitly opening the file again.) The close is effected at the time of the command only if there are no tasks currently accessing the file. A file that has been disabled by a SET FILE CLOSED command becomes enabled again by a subsequent SET FILE OPEN command. To distinguish a file that has been disabled by a SET FILE CLOSED from one that has been disabled by a SET FILE DISABLED command, the SET FILE CLOSED command closes the file with the UNENABLED attribute. A file with the DISABLED attribute can be enabled only by a SET FILE ENABLED command. A file with the UNENABLED attribute can be enabled by a SET FILE ENABLED or SET FILE OPEN command. ENabled|DIsabled specifies whether transactions can access the file. The values are: ENabled The file is available for use by transactions and, if closed, it is opened on the first request. If the command CEMT SET FILE(value) CLOSED ENABLED is given while the file is in use, the status of the file becomes `closed-unenabled'. If the command CEMT SET FILE(value) CLOSED is given while the file is in use, the file is disabled to prevent new users accessing the file. DIsabled The file is not available for use by transactions except for those that are currently using it. If there are any such users, `BEING DISABLED' is also displayed. The CEMT SET FILE DISABLED command has no effect on existing users; it simply prevents new users from accessing the file. The file can be reenabled by a SET FILE ENABLED command. (See also UNENABLED.) It is not possible to disable a remote file. EMptyrec|NOEMptyrec specifies whether the file is to be made empty when it is next opened. The values are: EMptyrec Indicates that when a file is being opened, its data is erased. NOEmptyrec Indicates that when a file is being opened, its data is not erased. ═══ 9.25. CEMT SET NETNAME ═══ CEMT SET NETNAME Function Change the attributes of named terminals in a network. Description The SET NETNAME command changes some of the values of a named terminal in a network. If you are familiar with network names, you may prefer to use this command as an alternative to CEMT SET TERMINAL. Syntax Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT SET NETNAME (the minimum abbreviation is CEMT S N) with (value), CLASS(value), or ALL. You get a display that lists the current status, similar to that obtained by CEMT INQUIRE NETNAME. You can then tab to the highlighted and blank fields and overtype them with the required values.  Type CEMT SET NETNAME (CEMT S N) with (value), or ALL, followed by one or more attribute settings that you wish to change. For example, cemt s n(value) i specifies that a named terminal is available for use (inservice). >>──CEMT Set Netname──┬─(value)─┬──┬─────────────────┬──┬────────────┬─────────> └─ALL─────┘ └─PRiority(value)─┘ ├─Inservice──┤ └─Outservice─┘ >──┬───────┬──┬────────────┬──┬──────────┬──>< ├─ATi───┤ ├─PUrge──────┤ ├─ACquired─┤ └─NOAti─┘ ├─Forcepurge─┤ └─RELeased─┘ └─CAncel─────┘ Options (value)|ALL specifies the identifier of the terminal for which the status is to be changed. The values are: (value) A netname identifier (1-8 characters) as specified in an installed terminal definition. If the netname is, for example, CICSS201, this option is coded thus: CEMT SET NETNAME(CICSS201) ALL Any changes you request are made to all resources of the specified type that you are authorized to access. PRiority(value) specifies the priority of a terminal relative to other terminals. The priority of a task is the sum of the transaction priority, the terminal priority, and the operator priority. Priority has no meaning for terminals that are ISC sessions being used as alternative facilities. The value must be in the range 0-255, where 255 is the highest priority. Inservice|Outservice specifies whether the terminal is available for use. The values are: Inservice The terminal is available for use. Outservice The terminal is not available for use. Setting a terminal OUTSERVICE means that the terminal can no longer be used by transactions. If PURGE or FORCEPURGE is also specified, any transaction using the terminal is terminated abnormally. If PURGE or FORCEPURGE is not specified, the transaction is allowed to terminate normally, but no further transactions are allowed to use the terminal. ATi|NOAti specifies whether the terminal is available for use by transactions that are initiated automatically from within CICS. The values are: ATi The terminal is available for use. NOAti The terminal is not available for use. PUrge|Forcepurge|CAncel purges the transactions running with this terminal. The values are: PUrge Any transaction running with this terminal is purged only if system and data integrity can be maintained. Forcepurge Any transaction running with this terminal is immediately terminated abnormally. Data integrity is not guaranteed. In some extreme cases (for example, if an error occurs during backout processing), CICS might terminate abnormally. CAncel AIDs queuing for the specified terminal are canceled. AIDs representing scheduled and allocated requests waiting in the local CICS system for the specified terminal are canceled. However, TD AIDs with an associated triggered task already started are not canceled. ACquired|RELeased specifies whether CICS is in session with the logical unit represented by this terminal. The values are: ACquired CICS is in session with the logical unit represented by the terminal. RELeased CICS is not in session with the logical unit represented by the terminal. Setting a terminal RELEASED causes the session to be terminated. Running transactions are allowed to finish unless PURGE or FORCEPURGE is also specified. ═══ 9.26. CEMT SET PROGRAM ═══ CEMT SET PROGRAM Function Change the attributes of installed programs. Description Syntax Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT SET PROGRAM (the minimum abbreviation is CEMT S P). You get a display that lists the current status, similar to that obtained by CEMT INQUIRE PROGRAM. You can then tab to the highlighted or blank fields and overtype them with the required values.  Type CEMT SET PROGRAM (CEMT S P) followed by one or more attribute settings that you wish to change. For example, cemt s p(pgrmid) e ne will reset the values for the named program to make it available for use (enabled) and a new copy of the program will be used when all the transactions currently using the program have finished (newcopy). >>──CEMT Set PRogram──┬─(value)─┬──┬──────────┬──┬─────────┬──┬────────┬──>< └─ALl─────┘ ├─Enabled──┤ ├─NEwcopy─┤ ├─CEDf───┤ └─DIsabled─┘ └─PHasein─┘ └─NOcedf─┘ Options (value) specifies a program identifier (1-8 characters), which is the name of a specific program entry in the table of installed program definitions. ALl specifies that any changes you request are to be made to all resources of the specified type that you are authorized to access. Enabled|DIsabled specifies whether the program is available for use. The values are: Enabled The program is available for use. DIsabled The program is not available for use. Programs beginning with "FAA" cannot be disabled because these characters are reserved for use by CICS. NEwcopy|PHasein specifies that a new version of the program needs to be loaded, and that the current program needs to be unloaded by CICS so that the user can replace the program. The values are: NEwcopy CICS is to unload the program immediately if the RESCOUNT is equal to zero. If the program is in use, this is an invalid request. Note: NEWCOPY cannot be specified for a program specified with the HOLD option. PHasein If the RESCOUNT is equal to zero, CICS unloads the program immediately, otherwise CICS unloads the program when RESCOUNT reaches zero. Note: PHASEIN cannot be specified for a program specified with the HOLD option. CEDf|NOcedf specifieswhat action the execution diagnostic facility (EDF) is to take for this program when the program runs under EDF. The values are: CEDf When EDF is active, CEDF initiation and termination screens are to be shown by CEDF while this program is running. Other screens are also to be shown unless the program was translated using the NOEDF translator option. NOcedf All CEDF activities, including initiation and termination screens, are to stop while this program is being processed. ═══ 9.27. CEMT SET SYSTEM ═══ CEMT SET SYSTEM Function Change the system attributes. Syntax Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT SET SYSTEM (The minimum abbreviation is CEMT S S). If you type just CEMT SET, the resources panel is displayed with System highlighted as the default. Press Enter to get the display that lists the current system status, similar to that obtained by CEMT INQUIRE SYSTEM. You can then tab to the blank field and overtype with the required value.  Type CEMT SET followed by the setting that you wish to change. Typing cemt s df(value) will reset the value of the default remote system. ┌─SYStem─┐ >>──CEMT Set──┴────────┴──┬───────────────────┬──>< └─Dfltremsys(value)─┘ Options Dfltremsys(value) specifies the name of the remote system to which CICS will direct unrecognized transaction codes. ═══ 9.28. CEMT SET TASK ═══ CEMT SET TASK Function Change the status of tasks. Description You cannot use the symbols * and + to specify a family of tasks. Syntax Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT SET TASK (the minimum abbreviation is CEMT S TA) with (value) or ALL. You get a display that lists the current status, similar to that obtained by CEMT INQUIRE TASK. You can then tab to the highlighted or blank fields and overtype them with the required values.  Type CEMT SET TASK (CEMT S TA) with number or ALL, followed by one or more attribute settings that you wish to change. For example, cemt s ta(value) pu will make the specified task purgeable in system-stall conditions. >>──CEMT Set TAsk──┬─(value)─┬──┬─────────────────┬──┬────────────┬──>< └─All─────┘ └─PRiority(value)─┘ ├─PUrge──────┤ └─FOrcepurge─┘ Options (value)|All specifies the identifier(s) of the task(s) for which the status is to be changed. The values are: (value) The CICS-generated task number. This is in the range 1-9999999. All Any changes you request are made to all resources of the specified type that you are authorized to access. PRiority(value) specifies the priority of the task, in the range 0-255 where 255 is the highest priority. PUrge|FOrcepurge purges the task in system stall conditions. The values are: PUrge The task is terminated. Task termination occurs only when system and data integrity can be maintained. FOrcepurge The task is terminated immediately. System integrity is not guaranteed. In some extreme cases, for example if a task is forcepurged during backout processing, CICS terminates abnormally. If you want to terminate a task but do not want to terminate CICS, you should use PURGE instead of FORCEPURGE. ═══ 9.29. CEMT SET TCLASS ═══ CEMT SET TCLASS Function Reset the maximum number of tasks for a transaction class. Description You cannot use the symbols * and + to specify a family of tasks. Syntax Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT SET TCLASS (the minimum abbreviation is CEMT S TC) with (value) or ALL. You get a display that lists the current status, similar to that obtained by CEMT INQUIRE TCLASS. You can then tab to the highlighted or blank fields and overtype them with the required values.  Type CEMT SET TCLASS (CEMT S TC) followed by one or more attribute settings that you wish to change. For example, cemt s tc(value) m(3) will reset the maxactive value to 3. >>──CEMT Set TClass──┬─(value)─┬──┬──────────────────┬──>< └─All─────┘ └─Maxactive(value)─┘ Options (value) specifies the 2-digit transaction class id. All specifies that any changes you request are made to all transaction classes. Maxactive(value) specifies the largest number of transactions in the transaction class which are allowed to run concurrently. The value can be in the range 0-99. Values greater than 99 are truncated. ═══ 9.30. CEMT SET TDQUEUE ═══ CEMT SET TDQUEUE Function Change the attributes of transient data queues. Description The SET TDQUEUE command changes some of the attributes of a transient data queue that is defined in the destination control table (DCT). The queue must not be REMOTE or INDIRECT. Syntax Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT SET TDQUEUE (the minimum abbreviation is CEMT S TD) with destid or ALL. You get a display that lists the current status, similar to that obtained by CEMT INQUIRE TDQUEUE. You can then tab to the highlighted or blank fields and overtype them with the required values.  Type CEMT SET TDQUEUE (CEMT S TD) with (value) or ALL, followed by one or more attribute settings that you wish to change. For example, cemt s td(value) en op will make a named extrapartition queue accessible by applications and open. >>──CEMT Set TDqueue──┬─(value)─┬──┬─────────────────────┬──┬──────────┬───────> └─All─────┘ └─TRIggerlevel(value)─┘ ├─ENabled──┤ └─Disabled─┘ >──┬────────┬──>< ├─Open───┤ └─Closed─┘ Options (value) specifies the identifier (1-4 characters) of a transient data queue. All specifies that any changes you request are made to all resources of the specified type that you are authorized to access. TRIggerlevel(value) specifies the number (0-32767) of requests for output to a queue that there must be before automatic transaction initiation (ATI) occurs. ENabled|Disabled specifies whether the queue can be accessed by applications. The values are: ENabled The queue can be accessed by applications. Disabled The queue cannot be accessed by applications, although it can still be open. Queues with names beginning with "C" cannot be disabled because they are usually reserved for use by CICS. Open|Closed specifies whether the extrapartition queue is open or closed. The values are: Open The queue is open. Closed The queue is closed. ═══ 9.31. CEMT SET TERMINAL ═══ CEMT SET TERMINAL Function Change the attributes of named terminals. Description The SET TERMINAL command changes some of the values of a named terminal defined in the terminal control table (TCT), or which has been autoinstalled. If you are familiar with network names, you may prefer to use the CEMT SET NETNAME command. Syntax Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT SET TERMINAL (the minimum abbreviation is CEMT S TE) with (value) or ALL. You get a display that lists the current status, similar to that obtained by CEMT INQUIRE TERMINAL. You can then tab to the highlighted or blank fields and overtype them with the required values.  Type CEMT SET TERMINAL (CEMT S TE) with (value) or ALL, followed by one or more attribute settings that you wish to change. For example, cemt s te(value) i specifies that a named terminal is available for use (inservice). >>──CEMT Set TErminal──┬─(value)─┬──┬─────────────────┬──┬────────────┬────────> └─ALL─────┘ └─PRiority(value)─┘ ├─Inservice──┤ └─Outservice─┘ >──┬───────┬──┬────────────┬──┬──────────┬──>< ├─ATi───┤ ├─PUrge──────┤ ├─ACquired─┤ └─NOAti─┘ ├─Forcepurge─┤ └─RELeased─┘ └─CAncel─────┘ Options (value)|ALL specifies the identifier(s) of the terminal(s) for which the status is to be changed. The values are: (value) A terminal identifier (1-4 characters) as specified in an installed terminal definition. If the terminal name is, for example, S201, this option is coded thus: CEMT SET TERMINAL(S201) ALL Any changes you request are made to all resources of the specified type that you are authorized to access. PRiority(value) specifies the priority of a terminal relative to other terminals. The priority of a task is the sum of the transaction priority, the terminal priority, and the operator priority. Priority has no meaning for terminals that are ISC sessions being used as alternative facilities. The value must be in the range 0-255, where 255 is the highest priority. Inservice|Outservice specifies whether the terminal is available for use. The values are: Inservice The terminal is available for use. Outservice The terminal is not available for use. Setting a terminal OUTSERVICE means that the terminal can no longer be used by transactions. If PURGE or FORCEPURGE is also specified, any transaction using the terminal is terminated abnormally. If PURGE or FORCEPURGE is not specified, the transaction is allowed to terminate normally, but no further transactions are allowed to use the terminal. ATi|NOAti specifies whether the terminal is available for use by transactions that are initiated automatically from within CICS. The values are: ATi The terminal is available for use. NOAti The terminal is not available for use. PUrge|Forcepurge|CAncel purges the transactions running with this terminal. The values are: PUrge Any transaction running with this terminal is purged only if system and data integrity can be maintained. Forcepurge Any transaction running with this terminal is immediately terminated abnormally. Data integrity is not guaranteed. In some extreme cases (for example, if an error occurs during backout processing), CICS might terminate abnormally. CAncel AIDs queuing for the specified terminal are canceled. AIDs representing scheduled and allocated requests waiting in the local CICS system for the specified terminal are canceled. However, TD AIDs with an associated triggered task already started are not canceled. ACquired|RELeased specifies whether CICS is in session with the logical unit represented by this terminal. The values are: ACquired CICS is in session with the logical unit represented by the terminal. RELeased CICS is not in session with the logical unit represented by the terminal. Setting a terminal RELEASED causes the session to be terminated. Running transactions are allowed to finish unless PURGE or FORCEPURGE is also specified. ═══ 9.32. CEMT SET TRANSACTION ═══ CEMT SET TRANSACTION Function Change some of the attributes of a selected transaction. Syntax Press the Clear key to clear the screen. There are two ways of commencing this transaction:  Type CEMT SET TRANSACTION (the minimum abbreviation is CEMT S TR) with (value), or ALL. You get a display that lists the current status, similar to that obtained by CEMT INQUIRE TRANSACTION. You can then tab to the highlighted or blank fields and overtype them with the required values.  Type CEMT SET TRANSACTION (CEMT S TR) followed by one or more attribute settings that you wish to change. For example, cemt s trans(value) e pu specifies that a named transaction is available for use (enabled) and is system-purgeable. >>──CEMT Set TRansaction──┬─(value)─┬──┬─────────────────┬─────────────────────> └─ALl─────┘ └─PRIority(value)─┘ >──┬───────────────┬──┬──────────┬──┬──────────────┬──>< └─TClass(value)─┘ ├─Enabled──┤ ├─PUrgeable────┤ └─Disabled─┘ └─NOTpurgeable─┘ Options (value) specifies a transaction identifier (1-4 characters). Only transactions that have been defined in the CICS system definition (CSD) file and installed on the running CICS system are accessible through CEMT. ALl specifies that any changes you request are made to all resources of the specified type that you are authorized to access. PRIority(value) specifies the priority of a transaction relative to other transactions. When a transaction is running as a CICS task, the priority of a task is the sum of the transaction priority, the terminal priority, and the operator priority. The "value" must be in the range 0-255, where 255 is the highest priority. TClass(value) specifies the 2-digit transaction class id to which the transaction belongs. If the transaction does not belong to a class, 00 is returned. The abbreviation for TCLASS is TC. Enabled|Disabled specifies whether the transaction is available for use. The values are: Enabled The transaction is available for use. Disabled The transaction is not available for use. Transactions that have identifiers beginning with "C" cannot be disabled because these are reserved for use by CICS. When the CEMT SET TRANSACTION DISABLED command is used, existing transactions run to completion before being DISABLED. Note: If a transaction is disabled, this does not prevent a START command which names this transaction from being shipped to a remote region. When a task is attached for the requested transaction, CICS checks that the transaction is enabled in the remote region. PUrgeable|NOTpurgeable specifies whether the transaction is purgeable in system stall conditions. The values are: PUrgeable The transaction is system-purgeable. NOTpurgeable The transaction cannot be purged. ═══ 10. Fundamentals of the CICS for OS/2 internal file manager ═══ This topic  Introduces the Internal File Manager of CICS for OS/2  Describes the key features which it provides. ═══ 10.1. Overview ═══ The internal file manager of CICS for OS/2 Version 3 is the Btrieve Microkernel Database Engine (MKDE) Version 6.20.925 supplied by Btrieve Technologies Inc. MKDE is a complete key-indexed record management system designed for high-performance data handling and improved programming productivity. CICS for OS/2 Version 2.0.1 used Btrieve Version 6.20.0, whereas CICS OS/2 Version 2.0 used Btrieve Version 6.15, and CICS OS/2 Version 1.20 used Btrieve Version 5.10. Note: If you have the Software Developers Kit for Version 5.10 or later, applications can access the File Manager outside the CICS for OS/2 environment. For information, see the CICS for OS/2 Application Programming book, and the Btrieve Programmer's Guide (available from Btrieve Technologies Inc). The following sections introduce some of the features that make the File Manager a uniquely powerful record management system. Note: This book discusses how CICS for OS/2 relates to MKDE, and does not discuss all of the available MKDE features. In the rest of this book MKDE is referred to simply as the File Manager. ═══ 10.2. Fundamental concepts of the File Manager ═══ This section describes the fundamental concepts behind the management of File Manager files, records, keys, and indexes. The File Manager stores information in File Manager data files. Inside each data file is a collection of records. A record contains bytes of data. That data might represent an employee's name, ID, address, phone number, rate of pay, and so on. For example, when CICS for OS/2 retrieves the record for Cliff Jones, the information might be displayed as follows: Jones Cliff D 340873 2341 Baxter Austin TX 512-555-2345 2146.00 Note: CICS for OS/2 applications are responsible for the appearance of data. The File Manager sees a record only as a collection of bytes. The File Manager does not recognize logically discrete pieces of information within a record. To the File Manager, there is no last name, first name, employee ID, and so on inside a record; there is just a collection of bytes. Because it is byte-oriented, the File Manager performs no translation or type verification of the data in a record. CICS for OS/2 applications must handle all information about the format and type of the data in the data file. For example, if a CICS for OS/2 application inserts or retrieves information about Cliff Jones into a File Manager file, it might use a data structure based on the following format: ┌─────────────────────────────────┬──────────┬─────────────────────────────────┐ │ INFORMATION IN RECORD │ LENGTH │ DATA TYPE │ │ │ IN BYTES │ │ ├─────────────────────────────────┼──────────┼─────────────────────────────────┤ │ Last name │ 25 │ Null-terminated string │ ├─────────────────────────────────┼──────────┼─────────────────────────────────┤ │ First name │ 25 │ Null-terminated string │ ├─────────────────────────────────┼──────────┼─────────────────────────────────┤ │ Middle initial │ 1 │ Char (byte) │ ├─────────────────────────────────┼──────────┼─────────────────────────────────┤ │ Employee ID │ 4 │ Long (4-byte unsigned binary) │ ├─────────────────────────────────┼──────────┼─────────────────────────────────┤ │ Street address │ 30 │ Null-terminated string │ ├─────────────────────────────────┼──────────┼─────────────────────────────────┤ │ City │ 25 │ Null-terminated string │ ├─────────────────────────────────┼──────────┼─────────────────────────────────┤ │ State │ 11 │ Null-terminated string │ ├─────────────────────────────────┼──────────┼─────────────────────────────────┤ │ Phone number │ 12 │ Null-terminated string │ ├─────────────────────────────────┼──────────┼─────────────────────────────────┤ │ Pay rate per month │ 4 │ Long (4-byte unsigned binary) │ └─────────────────────────────────┴──────────┴─────────────────────────────────┘ Inside the File Manager file, Cliff Jones' record would be stored as a collection of bytes. The following diagram shows a portion of the record for Cliff Jones, as it is stored in the File Manager file. Note: The diagram replaces ASCII values in strings with the appropriate letter or number. Integers and other numeric values are unchanged from their normal hexadecimal representation. 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ┌──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐ │ J│ o│ n│ e│ s│00│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ └──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘ 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F ┌──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐ │ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ C│ l│ i│ f│ f│00│ ?│ └──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘ 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F ┌──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐ │ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ └──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘ 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F ┌──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐ │ ?│ ?│ D│89│33│05│00│ 2│ 3│ 4│ 1│ │ B│ a│ x│ t│ └──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘ 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F ┌──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐ │ e│ r│00│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ ?│ .│ .│ .│ └──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘ The only discrete portions of information that the File Manager can recognize in a File Manager file are keys. CICS for OS/2 can designate any collection of bytes in a record as a key. Bytes must be contiguous inside each key segment. Keys and segments are discussed in detail beginning at Keys. The File Manager sorts records on the basis of the values in any specified key. The File Manager can also find a particular record based on a specified key value. In the preceding example, the 25 bytes that contain a last name in each record might be designated as a key in the File Manager file. CICS could use the last name key to obtain a listing of all the employees named Smith, or it could obtain a listing of all employees and then display that listing, sorted by last name. Keys also allow the File Manager to access information quickly. For each key defined in a File Manager data file, the File Manager builds an index. (Indexes are discussed in detail beginning at Indexes) The index is stored inside the File Manager data file itself, and contains a collection of pointers (addresses or offsets) into the actual data within that file. Associated with each pointer is a key value. In the preceding example, the key "last name" has an index. Inside that index is a collection of last names: one last name for every employee. For every last name in the index, there is also a pointer that indicates where the information about that employee is located in the File Manager data file: Budinszky 0222 Conrad 128C Doggett 1278 Hanlon 1164 Heater 1244 Khawaja 2816 Kreuger 0274 Schumacher 12FC Szalay 12A8 Wallace 2432 Woodward 12D0 Normally, when accessing or sorting information the File Manager does not search through all the data in its data file. Instead, it goes to the index, performs the search, and then manipulates only those records that meet the request. ═══ 10.3. Concurrent transactions ═══ A File Manager transaction is equivalent to a logical unit of work (LUW), and should not be confused with CICS transactions. Concurrent File Manager transactions allow CICS for OS/2 to run multiple transactions simultaneously for the same File Manager file (if the file uses the File Manager Version 6 format). Versions of File Manager prior to Version 6 support only one type of transaction: exclusive. In an exclusive transaction, File Manager locks the entire file for the duration of the transaction. This is known as file-level transaction locking. When a file is locked in an exclusive transaction, other transactions can still read the file (provided they are not involved in exclusive transactions and are not attempting to lock the file themselves). They cannot however, make any changes to the file. If the file uses a File Manager Version 6 format, other transactions do not see changes that occur during the transaction until that transaction ends. (If the file uses the File Manager Version 5 format, other transactions can see such changes.) With File Manager Version 6 a new type of transaction, concurrent, was introduced. When a File Manager Version 6 file is included in a concurrent transaction, modifications cause File Manager to lock only the record (or data pages, if the record is variable length) to be modified, as well as affected index pages. This allows other users to modify or include the same file in their own concurrent transaction, as long as no concurrent transaction has already locked the records to be modified (or any affected index pages). The following additional features apply to concurrent transactions:  Locked records remain locked for the duration of the transaction  If the transaction simply reads a record, File Manager does not lock the record  Other users cannot see the changes to a file in a transaction until the transaction ends. (Thus, if a system failure occurs before the transaction completes, other users will not have read false data; that is, data that is to be rolled back.) ═══ 10.4. File Manager files ═══ A file is the highest-level database entity you can access using the File Manager. The File Manager allows a maximum file size of approximately four gigabytes. You can create files online using the EXEC CICS SET FILE(xxxxxx) OPEN RESET command. Alternatively, you can create File Manager files and define their characteristics by using the CREATE command, which the File Manager Maintenance utility provides (see CREATE). Note, however, that you can use the CREATE command only to create CICS key-sequenced data set (KSDS) files. To create entry-sequenced data set (ESDS) and relative record (RRDS) files you must use the EXEC CICS SET FILE command, which is the recommended method of creating files. When creating files, the File Manager Version 6.20. uses a file format that allows faster data access than was possible with previous File Manager versions. This format is responsible for many of the enhancements and new features available in Version 6.20. Versions of the File Manager prior to Version 6.20 cannot open files that have the updated file format. However, File Manager Version 6.20 can open files that were created with earlier versions of File Manager, although it does not convert the files to the 6.20 file format. To take advantage of the performance gains provided by version 6.20. of the File Manager, you must perform this conversion first. For more information see Rebuilding existing File Manager files. ═══ 10.4.1. File components ═══ The File Manager files consist of a series of pages. A page is the unit of storage that the File Manager transfers between memory and disk. A File Manager file is composed of File Control Record (FCR) pages, data pages, index pages, and several other types of pages, all of which are discussed in the following sections. You specify a fixed size for each page when you create a file. The page size is always a multiple of 512 bytes, up to 4096 bytes. See Determining record and page size for more information. ═══ 10.4.1.1. FCR pages ═══ The first two pages in every File Manager file are the FCR pages. At any given time, the File Manager considers one of the FCR pages to be current. The current FCR page contains the latest information about the file, such as the file size, page size, alternate collating sequence name (if any), and other characteristics of the file. ═══ 10.4.1.2. Page allocation table ═══ Page allocation table (PAT) pages are part of the File Manager's internal implementation for converting between physical and logical page numbers in a File Manager file. The PAT tracks the mapping of logical page numbers to physical page numbers. ═══ 10.4.1.3. Data pages and variable pages ═══ Data pages contain fixed-length records, whereas variable pages contain variable-length records. (Records are discussed in detail beginning at Records) ═══ 10.4.1.4. Index pages ═══ Index pages are nodes in a B-tree structure. Each node contains key values for the data records. Generally, index pages contain many different key values. Each key value on the page has a record address. The File Manager uses this address to retrieve records containing a specified key value. See Indexes for more information. ═══ 10.4.2. File space allocation ═══ The File Manager automatically reallocates file space when you insert or delete File Manager records. The following paragraphs explain how the File Manager dynamically allocates space and uses free space. ═══ 10.4.2.1. Dynamic Expansion ═══ The File Manager allocates disk space as needed. If there is not enough room in the file when new records are inserted, the File Manager dynamically allocates additional data and index pages to the file. The size of each allocated page is the same as the page size with which the file was created. The File Manager also updates directory structures to reflect the new file size. When the File Manager allocates space to a file, that space remains allocated as long as the file exists. To reduce the space required for a file from which numerous records have been deleted, you can create a new file with the same characteristics as the original file. (To create this file, you can use the CLONE command in the File Manager Maintenance utility.) Then, use one of the following commands (or command sequences) in the File Manager Maintenance utility:  COPY  RECOVER, LOAD  SAVE, LOAD You can then delete the original file from the disk and rename the new file. The CICS for OS/2 internal File Manager and utilities describes the File Manager utilities. ═══ 10.4.2.2. Free space utilization ═══ When you delete a record, the disk space it formerly occupied is put on a free space list. When CICS for OS/2 inserts new records, the File Manager uses the free space instead of allocating additional pages to the file. The File Manager's method of reusing free space eliminates the need to reorganize files to reclaim disk space. ═══ 10.5. Records ═══ A record represents a set of logically associated data items in a File Manager file. Generally, a record is the unit transferred between CICS for OS/2 and the File Manager in a single operation. There is no inherent restriction on the number of records allowed in a File Manager file. A record can consist entirely of a fixed-length portion (a fixed-length record), or it can consist of a fixed-length portion followed by a variable-length portion (a variable-length record). All the keys defined for the file must be located within the fixed-length portion of the record. ═══ 10.5.1. Fixed-length records ═══ In a file that uses fixed-length records, the length of each record in that file must be the same. The maximum length of a fixed-length record depends on the physical page size and the number of duplicate keys you define for the file. The File Manager allows a fixed-length record to contain up to 4086 bytes (4096 minus 8 bytes for page overhead information, and 2 bytes for the record usage count). Therefore, the largest possible fixed-length record is 4086 bytes. See Determining record and page size for more information on maximum record length. In the file control table (FCT) you define records as fixed length by specifying the same values in the Maximum Record Length and Minimum Record Length fields. ═══ 10.5.2. Variable-length records ═══ Variable-length records store data of indeterminate length. When you create a File Manager file, you can specify that you want the file to use variable-length records. A variable-length record has a fixed-length portion and a variable-length portion. While the fixed-length portion of all variable-length records in a file must be the same size, the variable-length portion can vary. This means that the overall length of each variable-length record in the file can vary. A file is considered to contain variable-length records if the values in the Maximum Record Length and Minimum Record Length fields in the FCT are not the same. ═══ 10.5.2.1. Maximum length of variable-length records ═══ The maximum length of variable-length records supported by CICS for OS/2 and the File Manager is 32767 bytes. However, the ability to insert, update, and retrieve long records is influenced by several factors. ═══ 10.5.2.2. Free space list ═══ The File Manager maintains the Free Space List for variable pages. The Free Space List indicates which variable pages contain the same or more free space than that specified by the Free Space Threshold file specification. The Free Space Threshold file specification is a value you can specify when you create a file. This value is expressed as a percentage and tells the File Manager how much free space must remain on a variable page in order for that page to appear on the Free Space List. ═══ 10.6. Keys ═══ The File Manager uses keys to allow fast direct access to records in a File Manager file. Because the File Manager has no way of knowing the structure of the records in each file, you define each key by identifying the following:  The key's offset in bytes from the beginning of the record  The number of bytes you want to use for the key  The key's type (identifies how sorting is to be performed) For example, suppose a particular key begins at the eighth byte of the record and extends for four bytes. When you insert a record into the file, the File Manager extracts four bytes, beginning at the eighth byte, and uses this extracted value to position the record in the index. When you create a key, you can assign attribute and type information to it. Key attributes and types are closely related and must be used in conjunction with each other. ═══ 10.6.1. Key attributes ═══ The following key attributes are available with CICS for OS/2:  Segmented and nonsegmented  Duplicatable and nonduplicatable  Modifiable and nonmodifiable  Alternate collating sequence  Null and non-null. ═══ 10.6.1.1. Segmented and nonsegmented keys ═══ Keys can consist of one or more segments in each record. A segment can be any set of contiguous bytes in the record. The total length of a key equals the sum of the length of the key segments, and the maximum length is 255 bytes. Different key segments may overlap each other in the record. Note: When you assign an attribute to a key, all segments of that key share the same attributes. A File Manager file limits the maximum number of key segments (rather than the maximum number of keys). The maximum number of key segments allowed depends on the page size: Page Size Maximum Key Segments 512 8 1024 23 1536-4096 24 Note: For ESDS files the maximum number of key segments allowed is one less than the numbers shown above. See Determining record and page size for more information on calculating page size. A file with a page size of 512 bytes may contain 1 key with 8 segments, 8 keys with 1 segment each, or any combination in between. If a file has a page size of 1024 bytes, it may contain 1 key with 23 segments, 23 keys with 1 segment, or any combination in between. The key type can be different for each segment in the key. When a segmented key is a nonduplicatable key (see the following paragraph), the combination of the segments must form a unique value; however, individual segments may contain duplicates. When you are defining this type of segmented key, each segment would have duplicates=no as a key-level attribute even though that particular segment could have duplicates. To ensure that a particular segment is always unique, define it as a separate nonduplicatable key in addition to the segmented key definition. ═══ 10.6.1.2. Duplicatable and nonduplicatable keys ═══ If you define a key to be duplicatable, the File Manager allows more than one record to have the same value for that key. If you specify a key with no duplicates, the File Manager does not allow CICS for OS/2 to add multiple records with the same value in this key field. For example, in a file containing customer records, you can define the zip code as a duplicatable key so that many different records can contain the same value for the zip code. However, if you also make the customer number a key, you probably would not want to allow duplicates, since each customer should have a unique number. Note: If one segment of a segmented key allows duplicates, all of the segments must allow duplicates. For more information, see Segmented and nonsegmented keys. For information about how the File Manager stores duplicate key values, see Indexes. ═══ 10.6.1.3. Modifiable and nonmodifiable keys ═══ You can define a key as modifiable or nonmodifiable. If you define a key as modifiable, the File Manager allows CICS for OS/2 to update an existing record and change the value of the key. For example, if account balance is a key, you may allow a program to modify the value of that key as the customer makes purchases and payments. However, if the customer's account number is a key, you probably would make it a nonmodifiable key because the customer's account number should not change. Note: If one segment of a key is modifiable, all of the segments must be modifiable. ═══ 10.6.1.4. Alternate collating sequence ═══ You can direct the File Manager to sort string keys (type string) differently from the standard ASCII collating sequence. CICS for OS/2 provides the ability to sort keys in an EBCDIC sequence. You do this by specifying Y in the Alt key segment field in the FCT. ═══ 10.6.1.5. Null keys ═══ You can direct the File Manager to exclude certain records from an index by defining null keys. When you define a null key, you specify a null value by which the File Manager can recognize the key as being a null key. You can use a null value in a key when the data for the key is unavailable or when you do not want the File Manager to include a record for that key in the index. Null keys allow you to avoid searching through meaningless records in an index path and to eliminate the overhead time required to update the index each time a key with no meaningful data is inserted. When data becomes available for that key, and when you want to include the record in the index, you can update the record, replacing the null value with meaningful data. If you define one segment of a key as a null key, you must define all segments of that key as a null key. However, the File Manager allows you to define different null values for different segments in a segmented key. The most commonly used null values are ASCII blank (X'20') and binary 0 (X'00'). ═══ 10.6.2. Key types ═══ CICS for OS/2 supports two File Manager key types: string (code 0) and unsigned binary (code 14). Internally, the File Manager compares string keys on a byte-by-byte basis, from left to right. The File Manager sorts string keys according to their ASCII value. However, for string keys you can specify an alternate collating sequence. See Alternate collating sequence for more information. The File Manager compares unsigned binary keys a word at a time. It compares these keys from right to left because the Intel 8086 family of processors reverses the high and low bytes in an integer. The following sections, describe the key types and their internal storage formats. ═══ 10.6.2.1. String ═══ A string type in the File Manager is a sequence of characters ordered from left to right. Each character is represented in ASCII format in a single byte, except when the File Manager is determining whether a key value is null. ═══ 10.6.2.2. Unsigned binary ═══ The File Manager sorts unsigned binary keys as unsigned integers. An unsigned binary key must contain an even number of bytes (2, 4, 6, and so on). The File Manager compares unsigned binary keys a word at a time, from right to left. ═══ 10.7. Indexes ═══ An index is a structure in a File Manager file that contains the key values for a specific key. In an index, the File Manager dynamically maintains the key values in a sorted order, storing them in a balanced B-tree structure. When you insert, update, or delete a record, the File Manager adjusts all the indexes for the file to reflect the latest changes in the key values contained in the records. In addition to automatic index maintenance, the following index features are supported:  Up to 119 key segments per file  Adding or dropping any index after a file has been created  String and unsigned binary data types for key values  Numerous key attributes: duplicatable, nonduplicatable, modifiable, nonmodifiable, segmented, nonsegmented, alternate collating sequence, null, and non-null The File Manager keeps all indexes to the data records in the form of standard B-trees. A B-tree is a data structure that allows external searching by means of multiway tree branching. The B-tree structure features quick access and efficient use of disk space. Once a B-tree structure is created, no periodic maintenance is required. The File Manager creates a separate B-tree for each key you define within a file. You can delete, or drop, an index when a CICS for OS/2 application no longer needs it. The space that the index used in the file is freed for data or for other index pages. If you create an index at file creation time, the File Manager stores duplicate values in the chronological order in which the records are inserted into the file. Note: The chronological ordering of records can change when you update records and change their key values, when you drop and rebuild an index, or when you rebuild the File Manager file. Do not make your application dependent on the chronological ordering of records in a file. If you create an index for a file that was created earlier, The File Manager enters duplicate values into the index in the order in which their corresponding records are physically stored in the file at the time the index is created. You can also specify a key with an alternate collating sequence. For more information, refer to Alternate collating sequence. ═══ 10.8. Designing the database ═══ This section provides formulas and guidelines for designing your File Manager database. The topics covered should help you reduce the amount of disk space your files use, ensure automatic data recovery, support multiple transactions, and set up security. ═══ 10.8.1. Determining record and page size ═══ When you create a file, you must specify the logical record length and the file's page size. The following sections will help you determine these values. ═══ 10.8.2. Logical record length ═══ The logical record length is the number of bytes of fixed-length data you will allow a record to hold in the File Manager file you are creating. To obtain this value, calculate how many bytes of data you need to store in the fixed-length portion of each record. For example, the following table shows how the bytes in each fixed-length portion of the record are added together to obtain the logical record length: ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ VALUE │ NUMBER OF BYTES FOR VALUE │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Last name │ 25 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ First name │ 25 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Middle initial │ 1 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Employee ID │ 4 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Street address │ 30 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ City │ 25 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ State │ 11 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Phone │ 12 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Rate of pay │ 4 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Department │ 24 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Permanent/Temporary │ 1 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Miscellaneous │ 0 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ │ ──── │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Logical record length: │ 162 │ └───────────────────────────────────────┴──────────────────────────────────────┘ The Miscellaneous portion of the record is variable-length, and contains notes about the employee (commendations, bonuses, and so on). Because Miscellaneous is variable-length, it has no fixed-length, and therefore we need to reserve no bytes for its contents in each record. If any record actually has information to store in Miscellaneous, that information is stored on variable pages, and need not be included in the calculations for logical record length. Note: For files that allow variable-length records, logical record length refers only to the fixed-length portion of the record. ═══ 10.8.3. Page Size ═══ All pages in a File Manager data file are the same size. Therefore, when you determine what size the pages should be in your file, you must choose a size that meets the following criteria:  What page size is the smallest that will allow index pages to hold your largest key definition?  What page size is the optimum size for data pages? Once you have these values, you can select a page size that best fits your file. ═══ 10.8.3.1. Minimum page size for index pages ═══ To find the smallest page size that will still hold the largest key definition in your file, you must perform the following tasks: 1. Determine how many bytes the largest key in the file will require on an index page. This value is the sum of the user-specified key length and the overhead that the File Manager requires to store the key. The user-specified key length is a given quantity. To calculate the number of overhead bytes required, perform the following substeps: a. If the key does not allow duplicates, proceed to step 2. b. If the key does allow duplicates, add an additional 8 bytes to the user-specified key length. 2. Multiply the value you obtained in step 1 by 8. (The File Manager requires room for a minimum of 8 keys on a page.) 3. Add 12 to the value obtained in step 2. 4. Select the first page size that is equal to or greater than the value you obtained in step 3. Note: Remember that the page size you select in step 4 must accommodate the size of any keys created after file creation. Using the example from the preceding section, consider that your file will have four keys: ┌───────────────────────────────┬───────────────┬───────────────┬──────────────┐ │ KEY NAME │ SIZE IN BYTES │ NUMBER OF │ DUPLICATABLE?│ │ │ │ SEGMENTS │ │ ├───────────────────────────────┼───────────────┼───────────────┼──────────────┤ │ Last name │ 25 │ 1 │ Yes │ ├───────────────────────────────┼───────────────┼───────────────┼──────────────┤ │ Employee ID │ 4 │ 1 │ No │ ├───────────────────────────────┼───────────────┼───────────────┼──────────────┤ │ Department │ 24 │ 1 │ Yes │ ├───────────────────────────────┼───────────────┼───────────────┼──────────────┤ │ Permanent/Temporary │ 1 │ 1 │ Yes │ └───────────────────────────────┴───────────────┴───────────────┴──────────────┘ Given these values, you can calculate the minimum page size for your File Manager file's index pages as follows: in performing step 1 and its substeps, you can see that the largest key in the file (the last name key) requires a minimum of 25 bytes (its user-specified key length). In designing the file, you have decided that the last name key will allow duplicate values. Therefore, you would add 8 bytes for overhead to the user-specified key length of 25, giving you a total of 33 bytes. Performing step 2, you multiply 33 by 8, giving you a total of 264 bytes. Performing step 3, you add 12 bytes to the 264 bytes from step 2, giving you a total of 276 bytes. Performing step 4, you select the first page size that is equal to or greater than 276 bytes. Because the minimum File Manager page size is 512 bytes, you can select any possible page size. Although you have not eliminated any possible page sizes in this example, you must verify the minimum page size for index pages before choosing the optimum page size for data pages. Failure to do so may result in selecting a data page size that is incompatible with the allowable index page size. ═══ 10.8.3.2. Optimum page size for data pages ═══ Before you can determine the optimum size of your File Manager file's data pages, you must first calculate the file's physical record length. The physical record length is the sum of the logical record length and the overhead required to store a record on a data page of the File Manager file. The File Manager always stores a minimum of 2 bytes of overhead information in every record (as a usage count for that record). The File Manager also stores an additional number of bytes in each record, depending on how you define the records in your File Manager file. The following table shows how many bytes of overhead you must add to the logical record length to obtain the physical record length (based on how you define the records for your File Manager file): ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ TYPE OF OVERHEAD │ BYTES │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Record usage count │ 2 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Reserved duplicate pointers │ 8 (per pointer) │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Variable-length record pointer │ 4 (if file allows variable-length │ │ │ records) │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Record length │ 4 │ └───────────────────────────────────────┴──────────────────────────────────────┘ Using the example from earlier in this section, assume that you are creating a File Manager file with a logical record length of 162 bytes. To obtain the physical record length for this File Manager file, you would add the following values: ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ VALUE │ NUMBER OF BYTES FOR VALUE │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Logical record length │ 162 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Record usage count │ 2 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Variable-length record pointer │ 4 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ │ ──── │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ Physical record length: │ 168 │ └───────────────────────────────────────┴──────────────────────────────────────┘ Remember that for files with variable-length records, the logical record length refers only to the fixed-length portion of the record. Note: For files with compressed records, the data page format is different. (Compressed records are discussed in Data compression). A compressed record's entry on a data page consists of 7 bytes of overhead information, pointers for duplicate keys, reserved duplicate pointers (if any), and a 4-byte record-length field. The record's user-defined data is compressed and stored on variable pages. Using the physical record length that you calculated in the preceding paragraphs, you now can determine the file's optimum page size for data pages. The File Manager stores as many records as possible in each data page of the File Manager file; however, it does not break the fixed-length portion of a record across pages. Also in each data page, the File Manager stores eight bytes of overhead information. You must account for this additional overhead when determining the data page size. A File Manager file contains unused space if the page size you choose, less eight bytes (for overhead information), is not an exact multiple of the physical record length. To optimize your file's use of disk space, select a page size that can buffer your records with the least amount of unused space. Page size must always be a multiple of 512 bytes, up to 4096 bytes. Larger page sizes usually result in more efficient use of disk space. Consider the example from the preceding section, where the physical record length added up to 168 bytes. The following table shows how many records can be stored on a page and how many bytes of unused space remain on a page for each possible page size: ┌────────────┬────────────┬─────────────┬──────────────────────────────────────┐ │ PAGE SIZE │ RECORDS │ UNUSED │ │ │ │ PER PAGE │ BYTES │ │ ├────────────┼────────────┼─────────────┼──────────────────────────────────────┤ │ 512 │ 3 │ 0 │ (512 - 8 - ( 3 * 168)) │ ├────────────┼────────────┼─────────────┼──────────────────────────────────────┤ │ 1024 │ 6 │ 8 │ (1024 - 8 - ( 6 * 168)) │ ├────────────┼────────────┼─────────────┼──────────────────────────────────────┤ │ 1536 │ 9 │ 16 │ (1536 - 8 - ( 9 * 168)) │ ├────────────┼────────────┼─────────────┼──────────────────────────────────────┤ │ 2048 │ 12 │ 24 │ (2048 - 8 - ( 12 * 168)) │ ├────────────┼────────────┼─────────────┼──────────────────────────────────────┤ │ 2560 │ 15 │ 33 │ (2560 - 8 - ( 15 * 168)) │ ├────────────┼────────────┼─────────────┼──────────────────────────────────────┤ │ 3072 │ 18 │ 40 │ (3072 - 8 - ( 18 * 168)) │ ├────────────┼────────────┼─────────────┼──────────────────────────────────────┤ │ 3584 │ 21 │ 48 │ (3584 - 8 - ( 21 * 168)) │ ├────────────┼────────────┼─────────────┼──────────────────────────────────────┤ │ 4096 │ 24 │ 56 │ (4096 - 8 - ( 24 * 168)) │ └────────────┴────────────┴─────────────┴──────────────────────────────────────┘ As the table indicates, if you select a page size of 512, only 3 records can be stored per page. However, if you select a page size of 4096, 24 records can be stored per page and 56 bytes of each page will be unused. Note: The File Manager requires that each index page in the file be large enough to hold at least eight keys. If not, you must either increase the file's page size or decrease the key length. For more information, see Minimum page size for index pages. ═══ 10.9. Estimating file size ═══ You can estimate the number of pages, and therefore the number of bytes required to store a File Manager file with the formulas described in the following paragraphs. However, before using the formulas, realize that at any given moment, they only approximate file size because of the way that File Manager dynamically manipulates pages. Note: The following discussion and the formulas for determining file size do not apply to files that use data compression, since the record length for those files depends on the number of repeating characters in each record. While the formulas are based on the maximum storage required, they assume that only one transaction is updating or inserting records into the file at a time. File size increases if more than one transaction updates or inserts records into the file during simultaneous concurrent transactions. The formulas also assume that no records have yet been deleted from the file. Even if you delete half the records in a file, the file remains the same size. The File Manager does not deallocate the pages once occupied by deleted records; rather, File Manager re-uses them as new records are inserted into the file (before allocating new pages). If the final outcome of your calculations contains a fractional value, round the number to the next highest whole number. To estimate the size of your File Manager file, perform the following steps: 1. Calculate the number of data pages, using the following formula: Number of data pages = Number of records / ((Page size - 8) / (Physical record length)) To find the physical record length, use the following formula: Physical record length = Number of bytes of data in the fixed-length portion of the record + 2 bytes for the usage count + (8 * Number of keys at CREATE time allowing duplicates) + (8 * Number of reserved duplicate pointers) + 4 bytes if the record is a variable-length record + 2 bytes if blank truncation is allowed 2. Calculate the number of index pages for each defined key using one of the following formulas: For each key that does not allow duplicates: Number of index pages = (Number of records / ((Page size - 12) / (Key length + 8)) ) * 2 The B-tree index structure guarantees at least 50% usage of the index pages. Therefore, the index page calculations multiply the minimum number of index pages required by two to account for the maximum size. 3. If your file contains variable-length records, calculate the number of variable pages in the file and add that number to the sum from the preceding steps. To do so, use the following formula: Number of variable pages = (Total number of records in the file) / (Average number of records whose variable-length portion fits on a single page) Note: You can gain only a very rough estimate of the number of variable pages due to the difficulty in estimating the average number of records whose variable-length portion fits on the same page. 4. To the sum obtained in the preceding steps, add the following: 1 page: for each alternate collating sequence page used (if any) This new sum represents the estimated total number of logical pages that the file will contain. 5. Calculate the number of PAT pages, and add that number to the estimated number of logical pages from the preceding step. Every file has a minimum of two PAT pages; however, to calculate the number of PAT pages in a file, use the following formula: Number of PAT pages = ((Sum of pages in steps 1 through 3) * 4) / (Page size - 8 bytes for overhead) ) * 2 6. To the sum obtained in the preceding step, add 2 pages for the FCR pages. 7. Finally, add the estimated size of the pool of unused pages in the file. The File Manager uses the pool for shadow paging. To calculate the size of the pool, use the following formula: Size of the pool of unused pages = (Number of keys + 1) Having calculated the number of pages needed by the file, use the following formula to calculate the maximum number of bytes required to store the file: File size in bytes = Total file pages * Page size Note: Add an additional 4096 bytes to the size of the file if the file uses more than 30 PAT pages. The File Manager uses these additional bytes internally. ═══ 10.10. Conserving disk space ═══ The File Manager provides features that allow you to conserve disk space and improve system performance. These features include file preallocation, blank truncation, data compression, and index balancing. ═══ 10.10.1. File preallocation ═══ The File Manager lets you, via the CREATE command, preallocate up to 65535 pages to a file when you create a data file. Preallocation guarantees that disk space will be available when the File Manager needs it. To preallocate contiguous disk space for a file, the device on which you are creating the file must have the required number of bytes of contiguous free space available. The File Manager preallocates the number of pages you specify, whether or not the space on the disk is contiguous. If there is not enough space on the disk to preallocate the number of pages you specify, the File Manager returns Return Code 18 (Disk Full) and does not create the file. Use the formulas described in the previous section to determine the number of data and index pages the file requires. You should round any remainder from this part of the calculation to the next highest whole number. When you preallocate pages for a file, that file actually occupies that area of the disk. No other data file can use the preallocated area of disk until you delete or replace that file. As you insert records, the File Manager uses the preallocated space for data and indexes. When all of the preallocated space for the file is in use, the File Manager expands the file as new records are inserted. When you run the STAT command in the File Manager Maintenance utility, the File Manager returns the difference between the number of pages you allocated at the time you created the file and the number of pages that the File Manager has currently in use. This number is always less than the number of pages you specify for preallocation because the File Manager considers a certain number of pages to be in use when a file is created, even if you have not inserted any records. Once a file page is in use, it remains in use even if you delete all of the records stored on that page. When you delete a record, the File Manager maintains a list of free space in the file and reuses the available space when you insert new records. If the number of unused pages returned by STAT is zero, it does not always mean that there is no free space in the file. The number of unused pages can be zero if one of the following is true:  You did not preallocate any pages to the file.  All of the pages that you preallocated were in use at one time or another. ═══ 10.10.2. Blank truncation ═══ Blank truncation can be used only with variable-length records. When you define a file that allows variable-length records, you can specify using the CREATE command that File Manager use a blank truncation method for storing the records in order to conserve disk space. If you choose to truncate blanks, File Manager does not store any trailing blanks in the variable-length portion of the record when it writes the record to the file. Blank truncation has no effect on the fixed-length portion of a record. The File Manager does not remove blanks that are embedded in the data. When you read a record that contains truncated trailing blanks, File Manager expands the record to its original length. The value File Manager returns in the data buffer length parameter includes any expanded blanks. Blank truncation adds 2 bytes or 4 bytes of overhead to the physical size of the record (stored with the fixed record portion). ═══ 10.10.3. Data compression ═══ When you create a File Manager file via the CREATE command, you can specify whether you want the File Manager to compress the data records when it stores them in the file. Data compression can result in a significant reduction of the space needed to store records that contain many repeating characters. The File Manager will compress five or more of the same contiguous characters into 5 bytes. You should consider using the File Manager data compression in the following circumstances:  The records to be compressed are structured so that the benefits of using data compression are maximized.  The need for better disk utilization outweighs the possible increased processing and disk access times required for compressed files.  The computer running the File Manager can supply the extra memory used by the File Manager for compression buffers. The data compression option is most effective when each record has the potential for containing a large number of repeating characters. For example, a record may contain several fields, all of which may be initialized to blanks by a CICS for OS/2 application when it inserts the record into the file. Compression is more efficient if these fields are grouped together in the record, rather than being separated by fields containing other values. To use data compression, the file must have been created with the compression flag set. For more information about the compression flag, refer to Description files. ═══ 10.10.4. Index balancing ═══ The File Manager allows you to further conserve disk space by employing index balancing. By default, the File Manager does not use index balancing, so that each time a current index page is filled, the File Manager must create a new index page. When index balancing is active, the File Manager can frequently avoid creating a new index page each time a current index page is filled. Index balancing forces the File Manager to look for available space on adjoining index pages. If space is available on one of those pages, the File Manager moves keys from the full index page to the page with free space. The balancing process not only results in fewer index pages; it produces more densely populated indexes, better overall disk usage, and faster response on most read operations. If you add keys to the file in sorted order, index page usage increases from 50% to nearly 100% when you use index balancing. If you add keys randomly, the minimum index page usage increases from 50% to 66%. On write operations, the balancing logic requires the File Manager to examine more pages in the file and may possibly require more disk I/O. The extra disk I/O slows down file updates. Although the exact effects of balancing indexes vary in different situations, performance on write operations typically degrades by about 5-10% if you use index balancing. The File Manager files remain compatible regardless of whether index balancing is active. Also, you do not have to specify index balancing to access files that contain balanced index pages. You select index balancing by setting the Index balancing option in the MKDE Options Settings notebook, as described in Setting File Manager options. You can also specify index balancing for individual files when you create them using the CREATE command, see Balanced Key. ═══ 10.11. Memory management ═══ The cache is an area of memory that the File Manager reserves for buffering the pages that it reads. The cache is divided into a number of buffers, each of which is initially the size of the largest page CICS for OS/2 will access. Generally, a larger cache improves performance because it allows more pages to be in memory at a given time. The File Manager allows you to specify the amount of memory to reserve for the I/O cache buffers. If every cache buffer is full when the File Manager needs to transfer a new page into memory, a least-recently-used (LRU) algorithm determines which page in cache the File Manager should overwrite. The LRU algorithm reduces processing time by keeping the most recently referenced pages in memory. ═══ 10.12. Recovering data ═══ The File Manager provides a number of methods for recovering data. Some of these methods are automatic and require no interaction from your program or from an end-user. Others require some form of manual intervention. CAUTION: None of the following methods eliminate the need to back up files, since none can recover from a damaged disk. Therefore, it is imperative that backups be made to protect against the catastrophic loss of a file because of a hardware failure. ═══ 10.12.1. Automatic data recovery ═══ The File Manager provides the following automatic data recovery methods:  Shadow paging or pre-imaging (depending on the file's format)  Transaction control ═══ 10.12.1.1. Shadow paging ═══ The File Manager automatically guards against file corruption by using shadow paging. Shadow paging is especially useful when the File Manager needs to perform several physical page updates to process either a single non-transactional request or an entire transaction. Without shadow paging, if File Manager processing is interrupted during these operations by a system failure, files may be corrupted. Corrupted files may contain inconsistent index pages, and retrieving data from the file might be impossible. Shadow paging provides automatic protection against such corruption. ═══ 10.12.1.2. Transaction control and logging ═══ For the purposes of data recovery, the File Manager bundles one or more non-transactional operations and/or committed transactions as a so-called atomic set into a system transaction. A system transaction is a single unit of work done by the File Manager. A system transaction can include operations or transactions from one or more applications. However, unless a system failure occurs, system transactions are completely transparent to an application. A system transaction has nothing in common with either a concurrent transaction or an exclusive transaction. System transaction is a term specific to data recovery. ═══ 10.12.1.3. Transaction logging ═══ Transaction logging is a technique used to guarantee commitment of transactional data to disk. This technique involves recording file operations involved in a transaction to disk as the transaction progresses. At the same time, the normal transactional processing continues. The actual data file commitment can continue asynchronously after the transaction is completed or reaches a syncpoint. The transaction is guaranteed by the logged operations and in the case of system failure, any uncommitted data is rolled back into the data file from the system-transaction log file when the File Manager is restarted. Data in the system-transaction log file is organized by system transactions. Only when a system transaction is completed is the data within the log file treated as committed data. ═══ 10.12.1.4. Archival logging ═══ Archival logging takes advantage of the transaction logging feature to log operations on data files. The concepts of archival and transactional logging are the same, but involve different periods of time. Transactional logging generates log records for recovery purposes at a transactional (or atomic) level. Recovery is made for the last committed transaction. In contrast, archival logging records log records for a data file for extended periods of time, normally since the last backup was made. This type of recovery uses the backup file and the logged operations done on the file since the backup to restore the file, and is termed non-atomic. In transaction logging, the recorded log entries are only necessary until the transaction is committed, at which time the system-transaction log workspace can be reused. However, for archival logging, the recorded log entries cannot be discarded. The system-transaction log file is saved at semi-regular intervals for archival logging rather than reused. The saved log files are named in a sequential fashion to maintain correct ordering of transactions and non-transactional operations. In versions of the File Manager prior to Version 6.20, the log files were kept on an individual file basis. That is, for each data file there was a corresponding log file if the file was listed in the \BLOG\BLOG.CFG file. Therefore, to recover from a system crash using archival logging, the system-transaction log files must be converted to pre Version 6.20 log-file format. You do this using the BLOGGER utility, which takes the transaction log files generated by a File Manager and transposes the log entries into the individual log files as specified in the \BLOG\BLOG.CFG file on the drive where the data file resides. When the log files are transposed, you can use the Roll-forward utility PBROLL in the normal way (see Running the Roll Forward Utility). ═══ 10.12.2. Manual data recovery ═══ You can use the RECOVER command of the File Manager Maintenance utility to manually recover your data to a sequential file. The recovered data should reflect the status of the file before the interrupted operation began. If the system fails during a transaction, the File Manager rolls back all operations that completed after the start of the transaction but before the system failure. As with all transactions, either all changes within the transaction are made, or none are made. After you recover the data, use the CREATE or CLONE commands in the File Manager Maintenance utility to make a new, empty, identical File Manager file. Use the sequential file with the LOAD command of the File Manager Maintenance utility to insert the records into the newly created File Manager file. Refer to The File Manager Maintenance utility for more information on using the File Manager Maintenance utility. ═══ 10.13. Supporting multiple transactions ═══ The File Manager with CICS for OS/2 waits when multiple transactions attempt to access the same records simultaneously. Possible file touching conflicts shows the types of conflicts that can occur when User 1 is touching (reading or modifying) a file in the situations described in the far-left column of the table, and then User 2 attempts to touch the file in the ways listed in the top row of the table. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 3. Possible file touching conflicts │ ├───────────────────┬───────────────────┬───────────────────┬──────────────────┤ │ USER 2 │ NO TRANSACTION, │ NO TRANSACTION: │ CONCURRENT │ │ USER 1 │ OR CONCURRENT │ MODIFY │ TRANSACTION: │ │ │ TRANSACTION: READ │ │ READ WITHOUT │ │ │ WITHOUT LOCK │ │ LOCK OR MODIFY │ ├───────────────────┼───────────────────┼───────────────────┼──────────────────┤ │ NO TRANSACTION: │ No conflict │ No conflict │ No conflict │ │ READ WITHOUT LOCK │ │ │ │ ├───────────────────┼───────────────────┼───────────────────┼──────────────────┤ │ NO TRANSACTION: │ No conflict │ May conflict at │ May conflict at │ │ MODIFY │ │ the record level │ the record level │ │ │ │ │ (on user 2 │ │ │ │ │ modify) │ ├───────────────────┼───────────────────┼───────────────────┼──────────────────┤ │ CONCURRENT TRANS- │ May conflict at │ May conflict at │ May conflict at │ │ ACTION: READ │ the page level │ the page level │ the page level │ │ WITHOUT LOCK OR │ │ │ │ │ MODIFY │ │ │ │ └───────────────────┴───────────────────┴───────────────────┴──────────────────┘ Note: Possible file touching conflicts assumes that the files are for File Manager Version 6. If files for previous versions of the File Manager are used, locking occurs at file level. ═══ 11. The CICS for OS/2 internal File Manager and utilities ═══ This topic  Describes how you specify initialization options for the internal File Manager.  Describes the utilities associated with the internal File Manager: - The Maintenance utility, which allows you to create, manipulate and recover File Manager files. - The Roll Forward utility, which recovers changes made to a File Manager file between the time of the last backup and a system failure. - The Rebuild utility, which converts files from previous versions of the File Manager to the correct format for the current version. ═══ 11.1. The File Manager control panel ═══ The File Manager control panel allows the CICS for OS/2 system administrator or operator to specify initialization options for File Manager operation. The control panel also contains the message console, which displays the File Manager log messages. To display the File Manager control panel, enter START OS2MKDE at the OS/2 command prompt, if the File Manager is not already started. The File Manager control panel is displayed. The File Manager control panel contains three pulldowns: Engine Contains menu selections to allocate memory, threads, and semaphores, and perform shutdown. Options Allows the setting of initialization options. Help Provides access to the online help information. The help file OS2MKDE.HLP must be in the MKDE Home directory, see topic Setting system options. ═══ 11.1.1. The Engine pulldown menu ═══ On the File Manager control panel, the Engine menu contains options to allocate and free resources such as memory, threads, and semaphores. Allocate Resources Allows you to allocate the File Manager resources prior to the first CICS application initiating a session. When selected, all File Manager memory and thread resources will be allocated. Preallocation of resources can more easily determine any initialization problems without involving a CICS application. This option is disabled if resources have been allocated. Free Resources Allows you to free allocated memory and thread resources owned by the File Manager without shutting down the File Manager. This option is disabled unless resources have been allocated, and there are no active File Manager clients (that is CICS applications). Shutdown Shuts down the File Manager. If CICS applications are active at the time, a warning message is displayed. Shutting down the File Manager in this situation causes CICS applications to lose their connection with the File Manager, and may result in a loss of data. ═══ 11.1.2. Setting File Manager options ═══ To set File Manager options, select Settings from the Options pulldown menu on the control panel. The MKDE Options Settings notebook is displayed. You then select the various pages and set the File Manager options as required. The options are described in the following sections. You can only change options when CICS for OS/2 is not active, and you must stop and restart the File Manager before any changes take effect. You cannot change options while resources are allocated. However, if no client applications are active, you can select Free resources from the MKDE pulldown menu, before stopping the File Manager. When CICS for OS/2 starts again it will pick up the new settings. After you set option settings, you save them by selecting the Save pushbutton on the MKDE Options Settings notebook. The options are then written to the initialization file BTI.INI, and the notebook is closed. The saved option settings are used for subsequent invocations of the File Manager. If the File Manager cannot find a BTI.INI file, it will look for a NOVDB.INI file, which should be in the \CICS300\RUNTIME home directory. If you do not want to save the settings, you can select the Set pushbutton, which makes the File Manager use the current settings in the notebook in preference to those in the BTI.INI file. The settings are not saved to BTI.INI. The Cancel pushbutton ignores any changes since the option settings were last set, and closes the notebook. When you have specified the optimal option settings for CICS and saved them to the initialization file, select Lockout Changes from the Options pulldown menu. Changes to the option settings are then inhibited and the Options menu disappears. To restore the options settings to a set of default values, delete the BTI.INI file. ═══ 11.1.3. Setting files options ═══ Select Files in the Options Settings notebook and File options page 1 is displayed: File options page 1 The options for page 1 are concerned with operations on File Manager files: Number Of Open Files Enter a value in the range 1 through 64000. This is the maximum number of files that can be open at one time. You should set this value at least 10 higher than the number of files defined in the file control table (FCT). The default is 20. Number Of Handles Enter a value in the range 1 through 64000. This is the maximum number of logical file handles to be opened (for all files) at one time. Each open file can have multiple cursors (handles) assigned to individual client processes opening the same file. The default is 100. Note: This default is insufficient if you add FCT file definitions to the CICS control file, or if you migrate a control file containing FCT entries from a previous version of CICS. The minimum value specified should be (Value specified in the Maximum Number of Tasks field in the SIT plus 1) multiplied by the number of entries in the FCT. Also, on some types of hardware the value must be increased by 100, otherwise the system will wait for about 5 minutes during initialization. Number Of Record Locks Per Client Enter a value in the range 1 through 64000. This is the maximum number of record locks a client application may have at any one time. This is equivalent to the number of CICS files accessed in a CICS transaction logical unit of work (LUW), or the maximum number of file update requests made from a single LUW. The default is 50. Create Files in Pre-6x Format Select this check box to create all new files in the format that was used in versions of File Manager prior to Version 6. This is required for backward compatibility with previous versions of CICS for OS/2 and the File Manager. Log Specified Files Select this check box to cause all File Manager file operations performed on selected files to be logged. If this option is selected, the File Manager logs all operations that change any file listed in the BLOG.CFG file located in the drive where the File Manager file is located. You should place the BLOG.CFG file in a \BLOG directory of the root directory of the drive where the files to be logged reside. Note: Previous versions of the File Manager created individual log files for each data file. In version 6.20.0, File Manager operations are logged in the system-transaction log files (see Transaction logging). The roll forward utility program (PBROLL) cannot use this type of logfile. Therefore, you must use a conversion program (BLOGGER) to split the system-transaction log files into individual log files, which you can then roll forward using PBROLL. For more information on PBROLL, see Running the Roll Forward Utility. Index Balancing Select this check box to perform index balancing. By default, when an index page becomes full, the File Manager automatically creates a new index page and splits the values in the full index page between the two index pages. This option instructs the File Manager to not create a new page when an index page becomes full. Instead, the File Manager searches for available space in sibling index pages. The File Manager then rotates values from the full index page into pages that have available space. Index balancing increases page utilization, results in fewer index pages, and produces an even distribution of key values among nodes on the same level, thus increasing performance. However, the File Manager requires extra time to examine more index pages and requires more disk I/O. For more information on index balancing, see Index balancing. When you select the next page, Files options page 2 is displayed: Files options page 2 The options for page 2 are concerned with the sharing of files between different File Managers: Share Files On Local Disks Select this check box to control how opened File Manager files are accessed. Normally, the File Manager opens a file exclusively. However, this does not allow the file to be shared among other instances of the File Manager on the same or on different machines. Selecting this option causes files local to the executing File Manager to be opened in a shared mode. Concurrency between different File Managers is handled by file locking and physical disk I/O. If selected, this option may significantly degrade performance on the shared files. Share Files On Remote Disks Select this check box to specify how File Manager files on remote machines are accessed. This is identical to sharing on local disks, but applies to files on networked drives. If selected, this option may significantly degrade performance on the shared, remote files. Enable Sharing Bias on File Opens Selecting this option allows client applications to use an operational bias value to specify which individual files can be shared. Not selecting this option prevents client applications from using a shared access method other than those listed above in the panel, namely Share Files On Local Disks and Share Files On Remote Disks. Delete Temp Files Selecting this option causes the File Manager to delete any temporary files that have been created to control concurrency. On some peer-to-peer networks the deletion of temporary files may result in lock error (81) status codes being returned to an application. This is avoided by deselecting the option on this panel. System Transaction Hold Limit Enter a value in the range 1 through 256. This option controls how the File Manager performs system transactions. File sharing depends on an exclusive system transaction to maintain integrity for shared files during write operations. This option sets the number of system transactions the File Manager will perform before releasing exclusive write access to other File Managers with which it is sharing files. The default value is 1. ═══ 11.1.4. Setting memory options ═══ Select Memory in the Options Settings notebook and Memory options page 1 is displayed. Memory options page 1 The options for page 1 specify memory resource requirements. Maximum Record Size Enter a value in the range 1 through 64 representing the largest possible record length in KB to be used by the File Manager. The maximum record length determines the buffer size used by each worker thread to submit/return data between CICS and the File Manager. The default size is 32KB. Note: CICS for OS/2 supports a maximum record size of 32767 bytes. Extended Operation Work Buffer Enter the buffer size in the range 0 through 64KB. This buffer is used as a workspace in extended operations where multiple records are submitted or returned. The default size is 16KB. Largest Compressed Record Size Enter a value in the range 0 through 64KB representing the largest compressed record size. This allows creation of a memory buffer that the File Manager uses to compress and decompress records in a file created using the CREATE command with the Data Compression file attribute (see Data compression). The default size is 32KB. When you select the next page, Memory options page 2 is displayed: Memory options page 2 The options for page 2 are: Cache Allocation Enter a value in the range 64 through 65536KB. To achieve the best performance, allocate a cache size equal to the sum of the sizes of the files you are using. However, do not exceed the memory limitations of the machine on which the File Manager is running. Allocating an excessively large cache may result in virtual memory swapping to disk, which degrades performance. The default cache size is 512KB, which is the recommended minimum value. Maximum Sort Buffer Size Enter a value in the range 73 through 65536KB. You must select the check box before entering the required value. This option specifies the maximum amount of memory the File Manager may allocate for sorting purposes during run-time creation of indexes. If the memory required for sorting exceeds the size specified, or is greater than 50% of the available process memory, the File Manager creates a temporary file. The amount of available memory for a process is a dynamic value and varies according to system configuration and load. If you do not select this option, the File Manager allocates as much memory as needed up to 50% of the available memory. The default value is 73KB. Transaction Log Buffer Enter a value in the range 32 through 65536KB, specifying the maximum amount of memory that the File Manager may allocate for logging operations. This circular buffer is used to temporarily store logged operations until the next system transaction when the logged entries are written to the system transaction log file. This option is only valid when Log Specified Files (File option page 1) or Transaction Durability (Transaction options) are selected. The default value is 32KB. ═══ 11.1.5. Setting transactions options ═══ Select Transactions in the Options Settings notebook and Transactions options page 1 is displayed. Transactions options page 1 The options for page 1 are concerned with File Manager transactions: Maximum Concurrent Transactions Enter a value in the range 0 through 64000. This is the maximum number of concurrent File Manager transactions to be allowed. If the value is set to 0, no transactions are possible. The recommended minimum value is the value specified in the Maximum Number of Tasks field in the SIT plus 1. The default is 15. Transaction Durability Select this check box to specify how transactions are committed to permanent disk storage. Selecting this option causes the File Manager to complete the physical disk write of the LUW before returning a successful return code to the application. If this option is not selected, records are written to cache and the File Manager returns to the application before the data is written to disk. Note: If a system failure occurs before the cache buffer is flushed, and transaction durability is not enabled, data may be lost. If a system crash occurs during the commit to the data files, any uncommitted transactions are recovered from the log file when the File Manager is restarted. Disabling this setting prevents the File Manager from recovering uncommitted transactions, but provides enhanced performance. ═══ 11.1.6. Setting system options ═══ Select System in the Options Settings notebook and System options page 1 is displayed. System options page 1 The options for page 1 specify the number of thread resources, and in general, how the File Manager resources are allocated and released. Worker Threads Enter a value in the range 1 through 64. This is the number of File Manager worker threads available to respond to File Manager operation requests. Each worker thread allocates its own transfer buffer of the Maximum Record Size plus 500 bytes. The recommended minimum value is the value specified in the Maximum Number of Tasks field in the SIT plus 3. The default is 10. I/O threads Enter a value in the range 1 through 64. This is the number of disk read/write threads allocated by the File Manager. The optimum value is the value specified for Maximum Open Files plus 5 (excluding alternate index files). The recommended minimum value is the greater of (number of open files divided by 5) and 4. The default is 20. Thread Priority Delta Enter a delta value in the range -31 through +31. The background threads in the File Manager run at the highest priority class of TIME_CRITICAL (3). File Manager threads should always have a higher priority than that of the requesting CICS application. If a CICS application is required to run at the same highest priority class as File Manager, then the File Manager threads should have a slightly higher thread priority delta than the CICS application of the same priority class. This ensures optimal performance and response time. The default is 5. Maximum Active Clients Enter a value in the range 1 through 64000. This is the maximum number of client applications (this is, clients to the File Manager) that are to access the File Manager. The recommended minimum value is the value specified in the Maximum Number of Tasks field in the SIT plus 5. The default is 30. Return To Minimal State When Inactive Select this check box to make the File Manager free memory and thread resources and return to a minimal state when there are no active CICS applications. If this option is not selected, the File Manager retains all its allocated buffers and threads when CICS for OS/2 shuts down. When you select the next page, System options page 2 is displayed. System options page 2 The options for page 2 are concerned with File Manager internal system transactions. A system transaction represents a unit of work performed by the File Manager. For more information about system transactions, see Transaction logging. Operation Bundle Limit Enter a value in the range 1 through 6144, representing the maximum number of transactions (performed on any one file) required to trigger the system transaction. Any Insert, Update, or Delete operation not within a transaction is considered a single transaction. The File Manager performs a system transaction when it reaches the bundle limit or the Initiation Time Limit, whichever comes first. The default value is 100. Page Write Group Size Enter a value in the range 1 through 500, representing the maximum number of pages written in a group during a system transaction. Multiple page groups may be written during a system transaction. Between group writes, the I/O thread allows reads to occur. The default value is 30. Initiation Time Limit Enter a value in the range 1 through 120000 (2 minutes). This sets a time limit upon which a system transaction is to be triggered. The File Manager performs a system transaction when it reaches the Operation Bundle Limit or the initiation time limit, whichever comes first. The default value is 2000 milliseconds. Disk I/O Wait Time Enter a value in the range 0 through 10000 milliseconds. If a system transaction is currently being processed, and another system transaction is being requested, this setting specifies how long to wait before attempting to initiate the new system transaction. This setting is closely tied to the Initiation Time Limit and the speed of the disk I/O being performed. In general, a faster disk system requires a smaller I/O wait time. However, if the system transactions are large (a large Initiation Time Limit), the I/O wait time should be correspondingly longer. The default value is 1000 milliseconds. Transaction Log File Size Enter a value in the range 64 through 65536, representing the minimum size for the system-transaction log file. After the system-transaction log file size reaches this minimum, the File Manager looks for an opportunity to close the file and create a new one. This option is enabled only if Transaction Durability (Transaction options page) is enabled. The default value is 64KB. When you select the next page, System options page 3 is displayed. System options page 3 The options for page 3 specify directory locations used by the File Manager: The File Manager Home Directory Enter a directory for the File Manager to use as its "home base". The default home directory is \CICS300\RUNTIME. It is recommended that you do not change this value. The home directory is the location the File Manager uses for various items and as a default location for other items such as the Temporary Sorting Files directory. Among the items stored in the home directory are the BTI.INI or NOVDB.INI initialization file, and the File Manager executable. The directory must consist of a valid full path including a drive specification. The home directory is the only item written to the OS2.INI file and must be found when the File Manager is started. If the File Manager is started without a valid home directory, it prompts you for a new specification at startup. Temporary Sorting Files Enter a directory to specify where the File Manager can create temporary work files used for internal operations. The default directory is the Home directory. Transaction Log Directory Enter a directory to specify the location of the system-transaction log file (BTRVLOG.TRN). This log file is used for recovery purposes in case of a system failure. For both performance and recovery reasons, it should be placed in a location separate from the data files being accessed. The default directory is the Home directory. When you select the next page, System options page 4 is displayed. System options page 4 The options for page 4 specify startup and termination characteristics of the File Manager: Auto-Terminate Delay Enter a value in the range 0 through 120000 seconds. You must select the check box before entering the required value. You may wish the File Manager to not automatically terminate if it is to be used again in a short time. A good example of this is running Btrieve client programs in a batch mode environment. In this scenario, you do not want the File Manager to be loaded for each invocation of a client program. The Auto-terminate delay therefore specifies a time interval for the File Manager to wait before terminating. The default is 10 seconds. Save Window Position Select this check box to causes the File Manager to save the current window position, to be used the next time the File Manager is started. Allocate Resources At Startup Select this check box to instruct File Manager to allocate resources including threads and memory buffers when the File Manager is started. By default, the File Manager does not allocate any resources until the first operation request. ═══ 11.1.7. Setting User options ═══ Select User in the Options Settings notebook and User options page 1 is displayed. User options page 1 The options for page 1 are concerned with the message console and the message log file. Number Of Lines Allocated Enter a value in the range 1 through 256. This is the maximum number of display lines for the message console. The message console is a circular display window. When the number of message lines exceeds the maximum, all displayed messages are erased, and the display continues. Previous message texts are not lost as all are written to the message log file (BTRVLOG.MSG). The default value is 128. Log Messages To Disk Select this check box to create a log of all console messages. The message log file contains the text of all displayed messages, as well as startup and shutdown times for the File Manager. Message Log File Limit Enter a value in the range 1 through 4096KB. Before you can enter a value you must select the check box. The message log file contains the text of all displayed messages, as well as starting and termination times for the File Manager. The file is continually appended to by the File Manager, and so can get quite large over time. This option sets a limit on the size of this file. If the file is over this limit when the File Manager is started, you are asked whether to truncate the file or not. If you select not to truncate the file, the File Manager continues to append message texts to it. By not selecting the check box, the file grows continually without prompting the user. The default value is 256. Change Font Select this pushbutton to change the File Manager message console font. Selecting this pushbutton generates a standard font selection dialog through which you can select different fonts and attributes. When you select the next page, User options page 2 is displayed. User options page 2 The options for page 2 relate to actions taken by the File Manager that may require a response from the user. System Error Notification Select this check box so that when a critical error has occurred, a message box is displayed in addition to the message in the message console. This is helpful when the File Manager is in a minimized state. Startup Logo Select this check box so that the Btrieve logo is displayed when the File Manager is started. ═══ 11.2. The File Manager Maintenance utility ═══ The Maintenance utility (BUTIL.EXE) is a command line utility that allows you to create, manipulate, and recover File Manager data files. You can execute the Maintenance utility commands from the OS/2 command line or from a command file. ═══ 11.2.1. Utility overview ═══ This section provides information you need to know before using the Maintenance utility commands. It discusses the required command format, the concepts you should understand before running the Maintenance utility, and the use of command files. Note: If you have used the utility before, you may want to skip to the discussion of the individual commands, which begins on topic CLONE (the commands are discussed in alphabetic order). The BUTIL Maintenance utility cannot be used to create File Manager relative record data set (RRDS) or entry-sequenced data set (ESDS) format files. ═══ 11.2.2. Configuring the Maintenance utility ═══ You can use the environment variable BRQPARMS to override the default record size for BUTIL. This is necessary if the File Manager memory option Maximum record size has a value of less than 57000, which is the default maximum record size for BUTIL. To set BRQPARMS: SET BRQPARMS=/d:16500 Note: CICS for OS/2 supports a maximum file record size of 32767. ═══ 11.2.3. Command format ═══ The format for the Maintenance utility commands is as follows: BUTIL [-command [parameter ...]] | @commandFile -command A Maintenance utility command, such as COPY. You must precede the command with a dash (-), and you must enter a space before the dash. Maintenance Utility Commands lists the Maintenance utility commands. parameter Information that the command may require. The discussions of the individual commands (beginning on topic CLONE) provide details when applicable. commandFile Full pathname of a command file. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 4. Maintenance Utility Commands │ ├───────────────┬──────────────────────────────────────────────────────────────┤ │ COMMAND │ DESCRIPTION │ ├───────────────┼──────────────────────────────────────────────────────────────┤ │ CLONE │ Creates a new, empty File Manager file using an existing │ │ │ file's specifications. │ ├───────────────┼──────────────────────────────────────────────────────────────┤ │ COPY │ Copies the contents of one File Manager file to another. │ ├───────────────┼──────────────────────────────────────────────────────────────┤ │ CREATE │ Creates a File Manager file. │ ├───────────────┼──────────────────────────────────────────────────────────────┤ │ DROP │ Drops an index. │ ├───────────────┼──────────────────────────────────────────────────────────────┤ │ INDEX │ Creates an external index file. │ ├───────────────┼──────────────────────────────────────────────────────────────┤ │ LOAD │ Loads the contents of a sequential file into a File Manager │ │ │ file. │ ├───────────────┼──────────────────────────────────────────────────────────────┤ │ RECOVER │ Reads data sequentially from a File Manager file and writes │ │ │ the results to a sequential file. │ ├───────────────┼──────────────────────────────────────────────────────────────┤ │ SAVE │ Reads data along a key path and writes the results to a │ │ │ sequential file. │ ├───────────────┼──────────────────────────────────────────────────────────────┤ │ SINDEX │ Creates an index. │ ├───────────────┼──────────────────────────────────────────────────────────────┤ │ STAT │ Reports statistics about file attributes and current sizes │ │ │ of File Manager files. │ └───────────────┴──────────────────────────────────────────────────────────────┘ ═══ 11.2.4. Concepts ═══ The following paragraphs describe concepts you should understand before using the Maintenance utility commands. ═══ 11.2.4.1. Filenames ═══ For commands that require a filename, the name must include the full pathname, such as C:\DEMODATA\PATIENTS.DTA. ═══ 11.2.4.2. Description files ═══ A description file is an ASCII file containing information that the Maintenance utility commands CREATE, INDEX, and SINDEX need to perform their operations. Description files contain one or more elements. An element consists of a keyword, followed by an equal sign (=), followed by a value (with no space separator). Each element in the description file corresponds to a particular characteristic of a File Manager file or key definition. Description files provides more information. ═══ 11.2.5. Command files ═══ You can use a command file to do either of the following:  Execute a command that is too long to fit on the command line  Execute a command that you use often (by entering the command once in the command file and then executing the command file as often as you want). Command files contain the same information as that required on the command line. ═══ 11.2.5.1. Rules for command files ═══ Observe the following rules when creating a Maintenance utility command file:  You must limit each line to 130 characters.  You cannot split a single parameter across two lines.  You can specify only one command per command file. ═══ 11.2.5.2. Command file example ═══ The following is an example command file, COPYPATS.CMD. The file calls the BUTIL - CLONE command to clone the file PATIENTS.DTA. -CLONE c:\demodata\allpats.dta c:\demodata\patients.dta The following command uses the COPYPATS.CMD file: BUTIL @c:\demodata\copypats.cmd ═══ 11.2.6. Maintenance Utility commands ═══ This section describes the Maintenance utility commands and explains when and how to use each one. If you enter BUTIL on its own, the utility responds with a list of the available commands: ┌──────────────────────────────────────────────────────────────────────────────────┐ │ │ │ The command syntax is as follows: │ │ BUTIL -CLONE [/O] │ │ BUTIL -CLROWNER [/O] │ │ BUTIL @commandFile │ │ BUTIL -COPY [/O] │ │ [/O] │ │ BUTIL -CREATE │ │ BUTIL -DROP [/O] │ │ BUTIL -INDEX [/O] │ │ BUTIL -LOAD [/O] │ │ BUTIL -RECOVER [/O] │ │ BUTIL -SAVE [Y indexFile | N keynumber] │ │ [/O] │ │ BUTIL -SETOWNER [/O] │ │ BUTIL -SINDEX [/O] │ │ BUTIL -STAT [/O] │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────────────────────────────┘ Note: This panel shows some commands and options that are not supported by CICS for OS/2. ═══ 11.2.6.1. CLONE ═══ The CLONE command creates a new, empty File Manager file with the same file specifications as an existing file The new file includes all the defined key characteristics (such as key position, key length, or duplicate key values) contained in the existing file. ═══ 11.2.6.1.1. Format ═══ BUTIL -CLONE outputBtrvFile sourceBtrvFile outputBtrvFile The full pathname you want to use for the new, empty File Manager file. sourceBtrvFile The full pathname of the existing file that you want to replicate. The new file will not have an owner name. ═══ 11.2.6.1.2. Remarks ═══ The File Manager allows a maximum of 23 key segments in a File Manager file with a page size of 1024 bytes. Therefore, the CLONE command sets the page size in the new file to 2048 bytes if the existing file contains 24 key segments and has a page size of 1024 bytes. ═══ 11.2.6.1.3. Example ═══ The following command creates the NEWAPP.DTA file by cloning the PATIENTS.DTA file. BUTIL -CLONE c:\demodata\newapp.dta c:\demodata\patients.dta Note: If you are trying to recover from receiving Return Code 30 and you suspect that the header page of the source file might be damaged, try creating the new file by using the BUTIL -CREATE command with a description file. ═══ 11.2.6.2. COPY ═══ The COPY command copies the contents of one File Manager file to another. COPY retrieves each record in the input file and inserts it into the output file. The record size must be the same in both files. After copying the records, COPY displays the total number of records inserted into the new file. Note: COPY performs in a single step the same function as a RECOVER command followed by a LOAD command. By using the COPY command, you can create a File Manager file that contains data from an old file, but has new key characteristics. To do so, proceed as follows: 1. Use the CREATE command to create an empty file with the desired key characteristics (key position, key length, or duplicate key values). 2. Use the COPY command to copy the contents of the existing file into the newly created file. ═══ 11.2.6.2.1. Format ═══ BUTIL -COPY inputBtrvFile outputBtrvFile inputBtrvFile The full pathname of the file from which you want to transfer records. outputBtrvFile The full pathname of the file into which you want to insert records. The output file can contain data or be empty. ═══ 11.2.6.2.2. Example ═══ The following command copies the records in PATIENTS.DTA to NEWPATS.DTA. BUTIL -COPY c:\demodata\patients.dta c:\demodata\newpats.dta ═══ 11.2.6.3. CREATE ═══ The CREATE command generates an empty File Manager file using the characteristics you specify in a description file. Before you can use the CREATE command, you must create a description file to specify the new key characteristics. For more information, see Description files. ═══ 11.2.6.3.1. Format ═══ BUTIL -CREATE btrvFile descriptionFile btrvFile The full pathname of the File Manager file you want to create. If the pathname is the name of an existing File Manager file, this command creates a new, empty file in place of the existing file. Any data that was stored in the existing file is lost and cannot be recovered. However, the File Manager does not create a new file if you specify replace=n in the description file. (For an example, see Replace Existing File.) descriptionFile The full pathname of the description file containing the specifications for the new file. ═══ 11.2.6.3.2. Example ═══ The following command creates a file named PATIENTS.DTA using the description provided in the BUILD.DES description file: BUTIL -CREATE c:\patients.dta c:\build.des ═══ 11.2.6.3.3. Sample description file for the CREATE command ═══ The sample description file shown in Sample description file for the CREATE command creates a File Manager file. This file is specified to have a page size of 512 bytes and 1 key. The fixed-length portion of each record in the File Manager file is set to 98 bytes. Variable-length records with no blank truncation, and data compression are specified. The free space threshold is set to 20 percent. Allocation is set to 100 pages. The File Manager preallocates 100 pages, or 51200 bytes, when it creates the file. Sample description file for the CREATE command record=98 variable=y truncate=n compress=y ──┐ key=1 page=512 allocation=100 replace=n File fthreshold=20 ──┘ Specifications position=1 length=5 duplicates=y ──┐ modifiable=n type=string Key 0 null=y value=20 segment=y ──┘ Segment 1 position=6 length=10 duplicates=y ──┐ modifiable=n Key 0 null=y value=20 segment=n ──┘ Segment 2 Key 0 is a segmented key with two duplicatable, nonmodifiable string segments and a null value of X'20' (space) specified for both segments. ═══ 11.2.6.4. DROP ═══ The DROP command removes an index from a File Manager file and adjusts the key numbers of any remaining indexes, subtracting 1 from each subsequent key number. If you do not want to renumber the keys, you can add 128 to the key number you specify to be dropped. ═══ 11.2.6.4.1. Format ═══ BUTIL -DROP btrvFile keyNumber btrvFile The full pathname of the file from which you are dropping the index. keyNumber The number of the index you want to remove. If you want to preserve the original key numbers, add a 128 bias to the key number you specify. ═══ 11.2.6.4.2. Examples ═══ In both of the following examples, PATIENTS.DTA has three keys. The original keys in the file were numbered 0, 1, and 2. In the first example, the BUTIL -DROP command drops key number 1 from the PATIENTS.DTA file and renumbers the remaining key numbers as 0 and 1. BUTIL -DROP c:\demodata\patients.dta 1 In the following example, the BUTIL -DROP command drops key number 1 and does not renumber the keys. The key numbers remain 0 and 2. BUTIL -DROP c:\demodata\patients.dta 129 ═══ 11.2.6.5. INDEX ═══ The INDEX command builds an external index file for an existing File Manager file, based on a field not previously specified as a key in the existing file. Before you can use the INDEX command, you must create a description file to specify the new key characteristics. (For more information see Description files). The records in the new index file are sorted according to the values of the key field. Each contains:  The value of the key field  The 4-byte address of the record that contains this value. Note: If the key length you specify in the description file is 10 bytes, the record length of the external index file would be 14 bytes (10 plus the 4-byte address). ═══ 11.2.6.5.1. Format ═══ BUTIL -INDEX btrvFile indexFile descriptionFile btrvfile The full pathname of the existing file for which you want to build an external index. indexFile The full pathname of the index file in which the external index should be stored. descriptionFile The full pathname of the description file you have created containing the new key definition. The description file should contain a definition for each segment of the new key. ═══ 11.2.6.5.2. Remarks ═══ The INDEX command creates the external index file and then displays the number of records that were indexed. If you want to retrieve the file's records using the external index file, use the SAVE command (described in SAVE) ═══ 11.2.6.5.3. Sample description file for the INDEX command ═══ The description file shown in the following illustration defines a new key with one segment. The key begins at byte 30 of the record and is 10 bytes long. It allows duplicates, is modifiable, is a string type, and uses no alternate collating sequence. position=30 length=10 duplicates=y modifiable=y type=string alternate=n segment=n ═══ 11.2.6.5.4. Example ═══ The following command creates an external index file called NEWPAT.IDX using a file called PATIENTS.DTA. The description file containing the definition for the new key is called NEWIDX.DES. BUTIL -INDEX c:\demodata\patients.dta c:\demodata\newpat.idx c:\demodata\newidx.des ═══ 11.2.6.6. LOAD ═══ The LOAD command inserts records from an input sequential file into a File Manager file. LOAD performs no conversion on the data in the input sequential file. After the utility transfers the records to the File Manager file, it displays the total number of records loaded. Before running the LOAD command, you must create the input sequential file and the File Manager file. You can create the input sequential file using a standard text editor or an application; the input sequential file must have the required file format (as explained subsequently). You can create the File Manager file using either BUTIL -CREATE or BUTIL -CLONE. ═══ 11.2.6.6.1. Format ═══ BUTIL -LOAD inputFile btrvFile inputFile The full pathname of the ASCII sequential file containing the records to be loaded into a File Manager file. btrvfile The full pathname of the File Manager file into which you want to insert the records. ═══ 11.2.6.6.2. Required file format ═══ Records in the input sequential file must be in the following format:  The first field must be a left-adjusted integer (in ASCII) that provides the length of the record. This field does not include the carriage return or line feed. For files with fixed-length records, the length you specify should equal the record length of the File Manager file. For files with variable-length records, the length you specify must be at least as long as the minimum fixed length of the File Manager file.  A separator (either a comma or a blank) must follow the length field.  The record data follows the separator. The length of the data must be the exact number of bytes specified by the length field.  A carriage return/line feed (X'0D0A') must terminate each line. The carriage return/line feed is not included in the length value at the beginning of the line, and LOAD does not insert the carriage return/line feed into the File Manager file.  The last line in the file must consist of the end-of-file character (Ctrl+Z or X'1A'). The SAVE and RECOVER commands and most text editors automatically insert this character in the file. You can create an input sequential file using either a text editor or an application, as follows:  If you use a text editor to create the input sequential file, pad each record with blank spaces as necessary to fill the record to the length you specified at the beginning of the record. Fields containing binary data cannot be edited with most text editors.  If you use an application to create the input sequential file, append a carriage return/ line feed to the end of each record and include an end-of-file character (Ctrl+Z or X'1A') as the last line in the file. The sequential I/O calls provided by most high-level language processors insert carriage return, line feed, and end-of-file characters automatically. Format of records in the input sequential file shows the correct format for records in the input sequential file. For this example, the File Manager file has a defined record length of 40 bytes. Format of records in the input sequential file 40, The record follows the comma delimiter   └────────────────────────────────────┘  │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ Carriage Return │ │ │ or Line Feed │ └─ Comma Delimiter │ └───── Record Length Blank Pad for Proper Length ═══ 11.2.6.6.3. Example ═══ The following example loads sequential records from the PATIENTS.ADR file into the PATIENTS.DTA file. BUTIL -LOAD c:\demodata\patients.adr c:\demodata\patients.dta ═══ 11.2.6.7. RECOVER ═══ The RECOVER command extracts data from a File Manager file and places it in a sequential file that has the same format as the input sequential file used by the LOAD command. This is often useful for extracting some or all of the data from a damaged File Manager file. The RECOVER command may be able to retrieve many, if not all, of the file's records. You can then use the LOAD command to insert the recovered records into a new, undamaged File Manager file. Note: The Maintenance utility performs no conversion on the data in the records. Therefore, if you use a text editor to modify an output file containing binary data, be aware that some text editors may change the binary data, causing the results to be unpredictable. The RECOVER command performs the following actions:  Checks the file's Page Allocation Table (PAT) and reconstructs it, if transactions request this. The PAT is the part of the File Manager file that maintains a map of each page's physical location.  Reads records in physical order from the File Manager file.  Creates a sequential file that is compatible with the required format for the LOAD command. (See Required file format for more information about the format.)  Displays the total number of recovered records. ═══ 11.2.6.7.1. Format ═══ BUTIL -RECOVER btrvFile outputFile btrvfile The full pathname of the File Manager file from which you want to recover data. outputFile The full pathname of the ASCII sequential file where the utility should store the recovered records. ═══ 11.2.6.7.2. Remarks ═══ If the file's PAT is damaged, a prompt similar to the following appears: The file's Page Allocation Table seems to be damaged. BUTIL *strongly* recommends that you make a backup copy before continuing. Continue? 1=Yes 2=No By default, the prompt displays 2 (indicating No) on the next line. This allows you to exit the RECOVER command and back up the File Manager file before proceeding. If you have already backed up the File Manager file, enter 1 to continue running the RECOVER command. The RECOVER command allows you to set the File Manager file's page size. It displays the following prompt: Enter the page size or 0 to quit: 512 The value displayed at this prompt is the result of an attempt to determine the original page size of the File Manager file. If this value is incorrect, enter the correct page size. If you enter a page size that differs from the original page size, the result is unpredictable. If you are unsure of the correct page size, change the value as prompted by the utility. If the logical disk drive containing your output sequential file becomes full before the entire File Manager file has been recovered, the utility stops, indicates the number of records already recovered, and displays the following prompt: The disk volume is full. Enter new file name to continue or a period to quit. To continue running the RECOVER command using an additional output sequential file, complete one of the following steps:  If you are recovering the File Manager file to diskettes, remove the full diskette and replace it with another formatted diskette.  If you are recovering the File Manager file to a hard disk, specify another logical disk drive that has space available. In either case, enter the full pathname of the File Manager file you want to use to continue storing records, and then press the Enter key. The utility continues copying records from the File Manager file to the new output sequential file. This process creates multiple sequential files that you must load separately with the LOAD command. If the RECOVER command receives a variable page error (Return Code 54), it places all the data it can obtain from the current record in the output sequential file and continues the recovery process. Upon completion, the utility displays a message similar to the following: 16 records recovered. Operation completed successfully. ═══ 11.2.6.7.3. Example ═══ The following example extracts records from the PATIENTS.DTA file and writes them into the SEQPAT.DAT file. BUTIL -RECOVER c:\patients.dta c:\seqpat.dat ═══ 11.2.6.8. SAVE ═══ The SAVE command retrieves records from a File Manager file using a specified index path and places them in a sequential file that is compatible with the required format for the LOAD command. You can then edit the sequential file and use the LOAD command to store the edited data in another File Manager file. (For more information, see LOAD.) SAVE generates a single record in the output sequential file for each record in the input File Manager file. Upon completion, SAVE displays the total number of records saved. Note: The Maintenance utility performs no conversion on the data in the records. Therefore, if you use a text editor to modify an output file containing binary data, be aware that some text editors may change the binary data, causing the results to be unpredictable. ═══ 11.2.6.8.1. Format ═══ BUTIL -SAVE btrvFile outputFile [Y indexFile | N keyNumber] btrvfile The full pathname of the File Manager file containing the records you want to save. outputFile The full pathname of the ASCII sequential file in which you want the utility to store the records. indexFile The full pathname of an external index file by which you want to save records if you do not want to save records using the default of the lowest key number. keyNumber The key number (other than 0) by which you want to save records if you do not want to save records using the default of the lowest key number. ═══ 11.2.6.8.2. Remarks ═══ If the logical disk drive containing your output sequential file becomes full before the entire File Manager file has been saved, the utility stops, indicates the number of records already saved, and displays the following message: The disk volume is full. Enter new file name to continue or a period to quit. To continue the SAVE operation in another output sequential file, complete one of the following steps:  If you are saving the File Manager file to diskettes, remove the full diskette and replace it with another formatted diskette.  If you are saving the File Manager file to a hard disk, specify another drive that has space available. In either case, enter the full pathname of the File Manager file you want to use to continue storing records, and press the Enter key. The utility continues copying records from the File Manager file to the new output sequential file. Keep in mind that this process creates multiple sequential files that you must load separately with the LOAD command. ═══ 11.2.6.8.3. Examples ═══ The following two examples illustrate how to use the SAVE command to retrieve records from a File Manager file. The first example uses the NEWPAT.IDX external index file to retrieve records from the PATIENTS.DTA file and store them in an unformatted text file called PATIENTS.SAV: BUTIL -SAVE c:\demodata\patients.dta c:\demodata\patients.sav Y c:\demodata\newpat.idx The next example retrieves records from the PATIENTS.DTA file using key number 3 and stores them in an unformatted text file called PATIENTS.SAV: BUTIL -SAVE c:\demodata\patients.dta c:\demodata\patients.sav N 3 ═══ 11.2.6.9. SINDEX ═══ The SINDEX command creates an additional index for an existing File Manager file. The key number of the new index is one higher than the previous highest key number for the file. An exception is if a DROP command previously removed an index without renumbering the remaining keys, thus producing an unused key number; in this case, the new index receives the first unused number. Before you can use the SINDEX command, you must create a description file to define key specifications for the index. For more information see Description files. ═══ 11.2.6.9.1. Format ═══ BUTIL -SINDEX btrvFile descriptionFile btrvfile The full pathname of the file for which you are creating the index. descriptionFile The full pathname of the description file containing the description of the index you want to create. ═══ 11.2.6.9.2. Examples ═══ The following example adds an index to the PATIENTS.DTA file. The name of the description file is SUPPIDX.DES. BUTIL -SINDEX c:\demodata\patients.dta c:\suppidx.des ═══ 11.2.6.10. STAT ═══ The STAT command reports the defined characteristics of a File Manager file and statistics about the file's contents. ═══ 11.2.6.10.1. Format ═══ BUTIL -STAT btrvFile btrvFile The full pathname of the file for which you want to display statistics. ═══ 11.2.6.10.2. Example ═══ The following example retrieves the file statistics for the PATIENTS.DTA file. BUTIL -STAT sys:\system\515\patients.dta Output panel from STAT command shows the resulting output panel: Output panel from STAT command ┌──────────────────────────────────────────────────────────────────────────────────┐ │ │ │ File statistics for c:\demodata\patients.dta │ │ Record Length = 104 │ │ Compressed Records = No │ │ Variable Records = No │ │ Number of Keys = 3 │ │ Page Size = 2048 │ │ │ │ Unused pages = 0 │ │ Total Records = 16 │ │ File Version = 60 │ │ │ │ Key Length Modifiable Null │ │ Position Duplicates Type Total │ │ 0 21 20 Y Y -0 String ── 16 │ │ 0 7 12 Y Y -0 String ── 16 │ │ 1 1 6 N Y -0 String ── 16 │ │ 2 83 10 Y Y -0 String ── 7 │ │ │ │ Legend: Y = Yes, N = Nn, ??????? = Unknown │ │ - 0 The Alternate Collating Sequence is UPPER │ │ │ │ │ │ The command completed successfully. │ │ │ │ │ └──────────────────────────────────────────────────────────────────────────────────┘ This example shows that the file called PATIENTS.DTA was defined with a record length of 104 bytes, does not allow variable-length records, has 3 keys, and has a page size of 2048 bytes. Sixteen records have been inserted into the file. The file does not use data compression and is using all of its preallocated pages. Note: The STAT command designates key segments with the letter I, descending keys with the symbol <, manual keys with the letter M, alternate collating sequence keys with an asterisk (*). Indexes created with SINDEX are designated with the letter R by default unless you specified the Reserved Duplicate Pointer element. The remainder of the panel provides information about specific keys. For example, the panel shows that Key 0 allows duplicates, is modifiable, and consists of two segments:  The first segment starts in position 21, is 20 characters long, allows duplicates, is modifiable, and will be sorted as a string type. The dashes indicate that a null value was not defined. The Total column indicates that 16 unique key values were inserted for this key.  The second segment starts in position 7, is 12 characters long, allows duplicates, is modifiable, and will be sorted as a string type. Sixteen unique key values were inserted for this key. Key 1 consists of one segment. It starts in position 1, is 6 characters long, does not allow duplicates, is modifiable, and will be sorted as a string type. Sixteen unique key values were inserted for this key. Key 2 consists of one segment. It starts in position 83, is 10 characters long, allows duplicates, is modifiable, and will be sorted as a string type. Seven unique key values were inserted for this key. Refer to Keys for information on the concepts of keys. ═══ 11.3. Roll Forward utility ═══ The Roll Forward utility (PBROLL.EXE) is an OS/2 command line utility that recovers changes made to a File Manager file between the time of the last backup and a system failure. The changes are stored in a log file. If a system failure occurs, you can restore the backup copy of your File Manager file and run the Roll Forward utility. The utility applies the changes stored in the log file to your backup copy. You run PBROLL interactively. ═══ 11.3.1. Setting up files for logging ═══ To take advantage of the File Manager's logging feature and the Roll Forward utility, you must first set up your File Manager files for logging, as follows: 1. Create the log configuration file, BLOG.CFG. 2. Back up your data files before the logging begins. 3. Activate the File Manager's logging option by selecting Log specified files in the MKDE Options Settings notebook (as described in Setting File Manager options). The following sections explain each step. ═══ 11.3.2. Creating the log configuration file ═══ BLOG.CFG is the log configuration file. It specifies all File Manager files for which you want to log changes. You should create a BLOG directory at the root of each drive that contains File Manager files for which you want to log changes. You can then create a BLOG.CFG file in each BLOG directory and place entries in it, as follows: 1. Create the BLOG.CFG file. 2. Open the BLOG.CFG file. 3. For each File Manager file for which you want to log operations, create an entry using the following format: \directory1\btrvFile[=\directory2\logFile] directory1 The path to the file to be logged. Note: Do not include drive letters. btrvFile The name of the file to be logged. directory2 The path to the log file. If the log file and the File Manager file are on the same drive, you can omit the drive. If they are on different drives, you must include the drive letter. logFile The name of the log file. Make sure each entry fits completely on one line. You can place multiple entries on the same line, but they must be separated by at least one space. Each line can contain a maximum of 256 characters. If you do not provide a log name, the File Manager (at the time the file is first opened) assigns the original filename to the log file and gives it a .LOG extension. For example, if you did not specify a log name for the File Manager file TEST01.DAT in the directory TEST, the full name \TEST\TEST01.LOG is assigned to the associated log file. In this case, the default log file shares the same directory as the File Manager file. Note: You should avoid naming File Manager files with the same filename but different extensions, particularly if their entries in the BLOG.CFG file do not specify a log file name for each file. The next three examples show sample entries in the file \BLOG\BLOG.CFG. Each of these entries produces the same result: activity in the file \DATA\B.BTR is logged into the file \DATA\B.LOG. \data\b.btr \data\b.btr=\data\b.log \data\b.btr=c:\data\b.log The next example (again, a sample entry in \BLOG\BLOG.CFG) shows how to log activity to a different drive than the File Manager data file's drive. This entry directs the File Manager to log activity in the file C:\DATA\B.BTR into the log file D:\DATA\B.LOG. \data\b.btr=d:\data\b.log ═══ 11.3.3. Backing up data files ═══ Be sure to make a backup copy of your File Manager data files before logging begins. When logging is activated for a given file, the File Manager records (in the corresponding log file) all the operations that change that file. The File Manager continues appending subsequent operations to the end of this log file until the log file is deleted. Consequently, it is important to perform periodic maintenance to reduce the size of the log files. Note: Every time you back up your File Manager data files, delete the associated log files before executing any further operations that could change the files. Synchronization of the backup data files and the associated log files is critical to recovering operations successfully. ═══ 11.3.4. Running the Roll Forward Utility ═══ You run the Roll Forward utility from the OS/2 command line by entering PBROLL. Previous versions of the File Manager created individual log files for each data file. In Version 6.20.0, File Manager operations are logged in the system-transaction log files (see Transaction logging). PBROLL cannot use this type of log file. Therefore, you must use a conversion program (BLOGGER) to split the system-transaction log files into individual log files, which can then be rolled forward using PBROLL. To use the Roll Forward utility, you need to complete the following steps: 1. Run BLOGGER to split the transaction log files into individual log files. (Select Start on the BLOGGER panel.) 2. Set the Roll Forward utility's program options. 3. Place in the utility's queue all the items you intend to roll forward. 4. Start rolling forward the items in the queue. Following a brief description of the Roll Forward utility's pulldown menus, subsequent sections describe each of these steps in detail. ═══ 11.3.4.1. Using the Roll Forward pulldown menus ═══ After starting the Roll Forward utility, you can access two pulldown menus on the Roll Forward panel: Queue and Options. Note: If you are not using a mouse, you can access the menus by pressing and holding the Alt key while typing the letter highlighted in the menu selection. For example, to select the Queue pulldown menu, hold down the Alt key and press Q. To move between fields in the dialog boxes, use the Tab key. ═══ 11.3.4.1.1. Queue Menu ═══ When you select Queue from the main menu, a pulldown menu offers the following: Add... Generates a dialog box in which you can specify items to be placed in the queue. View... Generates a dialog box in which you can view the queued items. If no items are in the queue, this selection is disabled. Start Begins the process of rolling forward all items in the queue. Like the View... selection, this selection is disabled if no items are in the queue. Exit Exits the utility. You can also press F3 to exit. ═══ 11.3.4.1.2. Options menu ═══ When you select Options from the main menu, a pulldown menu offers the following: Options... Generates a dialog box that lets you set the data buffer length and the list options. About... Displays the version of the Roll Forward utility that you are running. ═══ 11.3.4.2. Setting options for the Roll Forward utility ═══ You should set program options for the Roll Forward utility before using the utility to roll forward changes. These options control the following:  Size of the data buffer used to retrieve records  Multitasking operation  Contents of the list file (BROLL.LST) The following list describes each of these options in detail. The subsequent section describes how to set the program options by using the Options pulldown menu. Program Option Description Data length Specifies the number of kilobytes allocated for the data buffer that the utility uses to process the logged entries. This number should be at least as large as the largest record to be rolled forward. The default is 4KB. Thread priority Specifies the priority of the Roll Forward thread. OS/2 provides true multitasking; the Roll Forward utility can always run concurrently with other applications. You can, however, vary the priority of the Roll Forward thread to accommodate other threads that are running. The following priorities are available:  Idle. Runs only when no other tasks are waiting for the CPU  Low. Lower priority than normal  Regular. The default thread priority  High. Higher priority than normal List Files Specifies the listing options for the list file BROLL.LST. You can select one of the following: Verbose For each logged file, this option adds the time stamps of the Roll Forward operation and log file creation to the list file. For each logged operation, it adds the name of the user who performed the operation, the internetwork address of the source workstation, the time stamp indicating when the operation was performed, and the user-defined lengths of data and key numbers used in the operation. Data to list Specifies the length of the data buffer that is printed in the list file for each operation that is rolled forward. Key to list Specifies the length of the key buffer that will be printed in the list file for each operation that is rolled forward. ASCII Lists the File Manager operation values in ASCII mode. Hex Lists the File Manager operation values in hexadecimal mode. ═══ 11.3.4.3. Using the Options menu ═══ To set Roll Forward options, use the Options pulldown menu: 1. Select Options from the Roll Forward main menu. 2. Select Options... from the Options pulldown menu to display the following dialog box: Roll Forward Options panel 3. Set the options using the guidelines provided in Setting options for the Roll Forward utility. 4. After setting the options, select one of the following pushbuttons:  Save-accepts and saves the changes you have made.  OK-accepts the changes but does not save them.  CANCEL-cancels the changes and returns to the previous panel. ═══ 11.3.4.4. Using the queue menu ═══ The Roll Forward utility works on a queued-job basis. When you specify the File Manager files that are to be rolled forward, the utility places them in the queue. This section discusses the Roll Forward utility's queue and explains how to do the following:  Add items to the queue  Delete items from the queue  Change list options for a queued item  View items in the queue. ═══ 11.3.4.4.1. Adding items to the queue ═══ The queue can hold a maximum of 32 items. Any of the following represents one item:  An individual File Manager file  A text file listing several File Manager files  A set of files specified with wildcards. To add items to the queue, complete the following steps: 1. Select Add... from the Queue pulldown menu. The Add... dialog box (similar to the following) appears: Roll Forward Add panel 2. Select the File Manager file or files to be rolled forward, as follows:  To select the entire drive, click on the Entire Volume check box.  To select a particular file, scroll the Directories list box (the list box on the right) to find your directory or drive. Double click on the directory name and then choose the filename from the Files list box (the list box on the left).  To select all available files with a certain extension, in the Filename text box enter a wildcard character for the filename, followed by the extension.  To select a text file containing a list of files, either choose the filename from the Files list box or type it in the Filename text box. 3. Specify the list option for the queue item you are adding, as follows:  If you want only to list the File Manager operations to be rolled forward (without actually rolling the logged operations forward), click on the List Only and List File check boxes. The operations will be listed in the file BROLL.LST in the BLOG directory.  If you want to list the operations in BROLL.LST and roll forward the operations, click on the List File check box.  If you do not want to list the operations that are rolled forward but you do want to roll the operations forward, do not click on either the List Only or List File check box. 4. If the File Manager file has an owner name, specify the owner name in the Owner text box. This is not supported by CICS for OS/2. 5. Click on the Add button to add the item to the queue. 6. Repeat Steps 2 through 5 to add each additional item to the queue. 7. To review the items you have placed in the queue, click on the Queue... button. The items selected appear on a panel similar to the following: Roll Forward Queue panel 8. When you have finished, click on the OK button. Note: At any time, you can click on the CANCEL button to cancel your changes and return to the previous panel. ═══ 11.3.4.4.2. Deleting items from the queue ═══ If you need to delete an item from the queue, perform the following steps: 1. Select View... from the Queue pulldown menu. 2. Select the item you want to delete. 3. Click on the Delete button to remove the item from the queue. 4. Click on the OK button. Note: If you change your mind and want to cancel your deletion, click on the CANCEL button instead of OK. ═══ 11.3.4.4.3. Changing list options for a queued item ═══ You can use either of the following methods to change the list options (that is, your choices regarding the List Only and List File check boxes) for a given queue item:  Select Add... from the Queue menu. Select the relevant item, choose the list option you prefer, and then click on the Add button.  Select View... from the Queue menu, select the relevant item, and choose the list option you prefer. ═══ 11.3.4.4.4. Viewing items in the queue ═══ You can use either of the following methods to view items in the queue:  From the Queue pulldown menu, select View... to display a dialog box that lists the queued items. (You can select this option only if the queue has one or more items in it.)  While you are adding items to the queue, click on the Queue... button to list the files in the queue. ═══ 11.3.4.5. Rolling forward items in the queue ═══ When the queue contains all the items for which you want to roll forward changes, you are ready to start the roll forward process. Select Start from the Queue pulldown menu. Note: The Roll Forward utility allows a maximum of 250 concurrent transactions per File Manager file during the roll forward process. After you select Start, the utility lists each File Manager file being rolled forward and specifies the number of logged entries for each file. (The number of logged entries is shown to the left of the filename.) To stop the roll forward process, select Abort. ═══ 11.4. Rebuilding existing File Manager files ═══ If your database contains files created with versions of the File Manager prior to Version 6.20, you may want to upgrade these files to take advantage of the Version 6.20 features. Version 6.20 of the File Manager works with Version 5 files; however, when using them it does not implement the Version 6.20 features. The Rebuild utility (BREBUILD.EXE) converts Version 5 File Manager data files to the Version 6.20 format. Run the Rebuild utility from the command line. The utility checks your entries and displays messages if the values you entered are not within the proper ranges. Before running the Rebuild utility, make sure you have unloaded your previous version of the File Manager, started Version 6.20, and backed up all your data files. Having a backup copy ensures against data loss if a power interruption occurs while you are running this utility. After rebuilding your files, be sure to check the utility's log file to see if any errors occurred during the conversion. The log file (BREBUILD.LOG) that the Rebuild utility creates is an ASCII text file. The .LOG file is placed in the current directory. You can view it using a text editor. ═══ 11.4.1. Running the Rebuild utility ═══ To run the Rebuild utility from the command line, enter the following command at the prompt: BREBUILD [-option ...] file or BREBUILD @commandFile option Specifies the configuration options for the utility. Precede each option letter with a dash (-). Do not place a space between the dash and the option letter nor between the option letter and its value. You can enter the option letter in uppercase or lowercase. -B[path:] Specifies an alternate location for the rebuilt files. (The default location is the current directory.) This option lets you rebuild large files on a different drive. Note: Do not use wildcard characters in the pathname you specify with the -B option. -C Instructs the utility to continue with the next file even if an error occurs. The utility notifies you of non-File Manager files or other errors but continues updating File Manager files. This option is useful if you have specified wildcard characters for the rebuilt files. -D Converts File Manager Version 5 supplemental indexes (which allow duplicates) to File Manager Version 6.15 indexes with duplicates. -M0|M2 Specifies the conversion method, as follows: M0 Clones and copies the files without dropping and replacing indexes. While this method is slower than M2, it is available in case you do not want to rebuild your indexes. M2 (Default) Clones the files, drops the indexes, copies the records into the new files, and rebuilds the indexes. Because this method is faster and creates smaller files, you should use it whenever possible. Note: The M2 method may create a Version 6.15 file in which the records are in a different physical order than in the original Version 5 file. -P[nnn] Specifies the page size (in bytes) of the new files. If you specify -P with no page size, the utility chooses the optimum page size for your file. Note: If you do not specify the -P parameter, the utility will change the page size if the original size will not work. For example, assume you have a Version 5 file with a page size of 1024 and 24 keys. Because File Manager Version 6.15 supports only 23 keys for a page size of 1024, the utility automatically selects a new page size for the file and displays an informative message on the screen. Note: If the CICS FCT entry is migrated from CICS for OS/2 Version 1.20 to CICS for OS/2 Version 2, ensure that any converted file definitions match the FCT definitions. -K[nn] Specifies the key by which the utility reads when rebuilding a file. If you do not specify this option, the utility reads the file in physical order. file Specifies the set of files to convert. Use full directory names. You may use wildcards (* and ?) in these filenames. @commandFile Specifies a command file for the utility to execute. You can include multiple entries in one command file. Each entry in the command file contains the utility options (if any) and the set of files to convert, followed by or [end]. When specifying the files to convert, be sure to use full directory names. You may use wildcards (* and ?) in these filenames. The following is an example of a Rebuild utility command file: -C c:\mydir\*.* -C -P1024 d:\dir\*.* -M0 -K0 c:\*.* ═══ 11.4.1.1. Examples ═══ The first example places the rebuilt files on the same drive: BREBUILD -B c:\newfiles -C -P4096 c:\oldfiles\*.btr The next example places the rebuilt files on a different drive: BREBUILD -B c:\btrfiles -C -P4096 -M2 d:\btrfiles\*.btr ═══ 11.4.2. Deleting temporary files ═══ By default, the Rebuild utility creates temporary files in the same directory in which the conversion takes place. (You can specify a different directory by using the -B option.) You need enough disk space to accommodate the original file and the new file while the Rebuild utility is running. Note: The Rebuild utility deletes the original file after rebuilding it, even if the new file is in a different directory. Normally, the Rebuild utility automatically deletes temporary files when the conversion is complete. However, if a power failure or other serious interruption occurs, the Rebuild utility may not delete the temporary files. If this occurs, look for filenames such as _T-xxxxx.TMP and delete them. ═══ 11.5. File Manager return codes ═══ You can get help with return codes by typing CICSHELP FAA6000 at the operating system prompt, or by typing CHLP FAA6000 on a clear CICS for OS/2 screen. This displays a series of panels with information about return codes. If you cannot find the return code in these panels, contact your support organization. ═══ 12. Description files ═══ A description file is an ASCII file containing information that the File Manager Maintenance utility commands CREATE, INDEX, and SINDEX need to perform their operations. Description files contain one or more elements. An element consists of a keyword, followed by an equal sign (=), followed by a value (with no space). Each element in the description file corresponds to a particular characteristic of a File Manager file or key definition. This appendix discusses the following topics:  Rules for description files  Description file example  Description file elements. ═══ 12.1. Rules for description files ═══ Use the following rules when creating a description file:  Enter elements in lowercase, as in the following example: type=string  Separate elements from each other with a separator (blank space, tab, or carriage return/line feed), as in the following example: record=4000 key=24  Specify the description file elements in the proper order. Summary of description file elements presents the elements in the appropriate order. Note: The order of the elements required for the CREATE, INDEX, and SINDEX commands is the same. However, these commands do not all require the same elements.  Address all element dependencies. For example, consider the following Null Key element: null=y If you specify this element in the description file, you must also include the Null Key Value element.  Define as many keys as you specify with the Key Count element. The following example specifies 12 keys for the file: key=12 In this case, you must define 12 keys in the description file, each consisting of one or more segments.  For a key with multiple segments, you must define the following elements for each key segment: - Key Position - Key Length - Duplicate Key Values - Modifiable Key Values - Key Type - Alternate Collating Sequence  If any key in the file uses an alternate collating sequence, include either an alternate collating sequence filename or a country ID and code page ID. You can include this information as either the last element of the key segment or the last element in the description file.  If a description file element is optional, you can omit it from the description file.  Make sure the description file contains no text formatting characters. Some word processors embed formatting characters in a text file. ═══ 12.2. Description file example ═══ The sample description file shown in Sample description file using alternate collating sequence filename creates a File Manager file. This File Manager file has a page size of 512 bytes and 1 key. The fixed-length portion of the record is 98 bytes long. The file allows variable-length records but does not use blank truncation. The file uses data compression, and has the free space threshold set to 20 percent. The File Manager preallocates 100 pages, or 51200 bytes, when it creates the file. The file has one key segmented with two segments. Sample description file using alternate collating sequence filename record=98 variable=y truncate=n compress=y ──┐ key=1 page=512 allocation=100 replace=n  File fthreshold=20 ──┘ Specifications position=1 length=5 duplicates=y ──┐ modifiable=n type=string  Key 0 null=y value=20 segment=y ──┘ Segment 1 position=6 length=10 duplicates=y ──┐ modifiable=n type=string  Key 0 null=y value=20 segment=n ──┘ Segment 2 ═══ 12.3. Description file elements ═══ Summary of description file elements lists the description file elements in the order in which they must appear in the description file. For each element, Summary of description file elements specifies the required format, the range of acceptable values, and the associated commands. An asterisk (*) after the element name indicates that the element is optional. Descriptions of the individual elements follow the table. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 5. Summary of description file elements │ ├─────────────────────┬──────────────────────┬───────────┬─────────────────────┤ │ ELEMENT │ FORMAT │ RANGE │ COMMAND │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Record Length │ record=nnn │ 4-4088 │ CREATE │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Variable-Length │ variable= │ N/A │ CREATE │ │ Records │ │ │ │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Reserved Duplicate │ dupkey= │ 1-24 │ CREATE │ │ Pointer* │ │ │ │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Blank Truncation* │ truncate= │ N/A │ CREATE │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Data Compression* │ compress= │ N/A │ CREATE │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Key Count │ key=nnn │ 0-24 │ CREATE │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Page Size │ page=nnnn │ 512-4096 │ CREATE │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Page Preallocation* │ allocation=nnnnn │ 1-65535 │ CREATE │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Replace Existing │ replace= │ N/A │ CREATE │ │ File* │ │ │ │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Free Space │ fthreshold=<10|20|30>│ N/A │ CREATE │ │ Threshold* │ │ │ │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Balanced Key* │ balance= │ N/A │ CREATE │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Key Position │ position=nnnn │ 1-4088 │ CREATE, INDEX, │ │ │ │ │ SINDEX │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Key Length │ length=nnn │ key type │ CREATE, INDEX, │ │ │ │ limit │ SINDEX │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Duplicate Key │ duplicates= │ N/A │ CREATE, INDEX, │ │ Values │ │ │ SINDEX │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Modifiable Key │ modifiable= │ N/A │ CREATE, INDEX, │ │ Values │ │ │ SINDEX │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Key Type │ type=validBtrieveKeyT│pN/A │ CREATE, INDEX, │ │ │ │ │ SINDEX │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Alternate Collating │ alternate= │ N/A │ CREATE, INDEX, │ │ Sequence* │ │ │ SINDEX │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Manual Key* │ manual= │ N/A │ CREATE, INDEX, │ │ │ │ │ SINDEX │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Null Key │ null= │ N/A │ CREATE, INDEX, │ │ │ │ │ SINDEX │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Null Key Value │ value=nn │ 1-byte │ CREATE, INDEX, │ │ │ │ hex │ SINDEX │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Segmented Key │ segment= │ N/A │ CREATE, INDEX, │ │ │ │ │ SINDEX │ ├─────────────────────┼──────────────────────┼───────────┼─────────────────────┤ │ Alternate Collating │ name=sequenceFile or │ valid │ CREATE, INDEX, │ │ Sequence │ countryid=nnn and │ path or │ SINDEX │ │ Filename/ID │ codepageid=nnn │ values │ │ │ │ │ valid to │ │ │ │ │ operating │ │ │ │ │ system or │ │ │ │ │ -1 │ │ │ │ │ (default) │ │ └─────────────────────┴──────────────────────┴───────────┴─────────────────────┘ ═══ 12.3.1. Record Length ═══ Format: record=nnnn Range: 4 through 4088 bytes Command: CREATE The Record Length element defines the logical data record length in bytes. For fixed-length records, this value should correspond to the length of the data buffer parameter that performs operations on the file. For variable-length records, this value should correspond to the fixed-length portion of the record. The data record length must be at least 4 bytes and must be large enough to contain all the keys defined for the file. The record length (including its duplicate key overhead and usage count overhead) plus 6 bytes must not exceed the file's page size. ═══ 12.3.2. Variable-Length Records ═══ Format: variable= Range: Not applicable Command: CREATE The Variable-Length Records element specifies whether the file will contain variable-length records. If a record is variable length, the maximum fixed-length record is decreased by 4 bytes. Specify y if you want the file to allow variable-length records; otherwise, specify n. ═══ 12.3.3. Reserved Duplicate Pointer ═══ Format: dupkey=nnn Range: 1 through 24 Command: CREATE The Reserved Duplicate Pointer element is optional. It specifies the number of duplicate key pointers to preallocate for the file when it is created. Each reserved duplicate pointer adds 8 bytes of extra storage space to the fixed record length. These reserved pointers can be used when keys that allow duplicates are added after the file is created. ═══ 12.3.4. Blank Truncation ═══ Format: truncate= Range: Not applicable Command: CREATE The Blank Truncation element is optional. It specifies whether the File Manager performs blank truncation on variable-length records. The truncate element has an effect only if you specify y for the Variable-Length Records element. Specify y if you want the File Manager to use blank truncation. Otherwise, either specify n or omit this element from your description file. ═══ 12.3.5. Data Compression ═══ Format: compress= Range: Not applicable Command: CREATE The Data Compression element is optional. It specifies whether the File Manager performs data compression on records that are inserted into the file. Specify y if you want the File Manager to perform data compression. Otherwise, either specify n or omit this element from your description file. ═══ 12.3.6. Key Count ═══ Format: key=nnn Range: 0 through 24 (see Key Segment Count Values) Command: CREATE The Key Count element specifies the number of keys to be defined in the file. The file's page size limits the amount of key segments a file can have. Key Segment Count Values shows the maximum key count values for each possible page size. This value represents the number of key segments, not the number of keys. There may actually be more segment definitions than the key count. For example, assume a file contains three keys: key 0 has two segments, key 1 has four segments, and key 2 has two segments. In this example, the file has a page size of 512, the value specified for the Key Count element is 3, and the maximum number of key segments is eight. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 6. Key Segment Count Values │ ├───────────────────────────────────────┬──────────────────────────────────────┤ │ PAGE SIZE (IN BYTES) │ MAXIMUM NUMBER OF KEY SEGMENTS │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ 512 │ 8 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ 1024 │ 23 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ 1536-4096 │ 24 │ └───────────────────────────────────────┴──────────────────────────────────────┘ ═══ 12.3.7. Page Size ═══ Format: page=nnnn Range: 512 through 4096 bytes Command: CREATE The Page Size element specifies the physical page size (in bytes) for the file. You can specify any multiple of 512, up to 4096. Note: For optimum performance, set the page size to 512, 1024, 2048, or 4096 bytes. ═══ 12.3.8. Page Preallocation ═══ Format: allocation=nnnnn Range: 1 through 65535 Command: CREATE The Page Preallocation element is optional. It specifies the number of pages to preallocate to the file. If you do not want to preallocate any pages, either specify n or omit this element from your description file. ═══ 12.3.9. Replace Existing File ═══ Format: replace= Range: Not applicable Command: CREATE The Replace Existing File element is optional. If you do not want to create a new, empty file over an existing File Manager file of the same name, specify n. If you want to replace an existing File Manager file with a new, empty file of the same name, either specify y, or omit this element from your description file. ═══ 12.3.10. Free Space Threshold ═══ Format: fthreshold=<10|20|30> Range: Not applicable Command: CREATE The File Manager stores the variable-length portions of records on their own pages (called variable pages), separate from the fixed-length portion of the record (which is stored on a data page). The File Manager maintains the Free Space List for variable pages. The Free Space List indicates which variable pages contain the same or more free space than that specified by the Free Space Threshold file specification. You can specify a value for the Free Space Threshold element when you create the file. This value is expressed as a percentage and tells the File Manager how much free space must remain on a variable page in order for that page to appear on the Free Space List. When the File Manager adds new variable-length records to the file, it uses pages in the Free Space List before using new variable pages. After each Insert, Update, or Delete operation, the File Manager rechecks the remaining space on the affected variable page to see if it is still above the threshold to qualify for the Free Space List. The free space threshold feature provides a means of reducing the fragmentation of variable-length records across several pages. A higher free space threshold reduces fragmentation at the cost of requiring more disk space for the file. You can specify any two-digit number for this element, and the utility rounds it to 10, 20, or 30. The File Manager uses a default free space threshold of 5% if either of the following is true:  You specify a value less than 10.  You do not specify a value here but have specified y for the Variable-Length Records element. Note: If the File Manager file does not allow variable-length records, do not include this element in the description file. ═══ 12.3.11. Balanced Key ═══ Format: balance= Range: Not applicable Commands: CREATE The Balanced Key element is optional. This feature allows you to use index balancing. With index balancing, the File Manager looks for available space in sibling index pages each time an index page becomes full and then rotates values from the full page into the pages with space available. Index balancing increases key page utilization, results in fewer pages, and produces an even distribution of keys among nodes on the same level, thus enhancing performance. Note: When you specify index balancing for a specific file, the File Manager will always balance that file's keys. To use index balancing, specify y. Otherwise, either specify n or omit this element from the description file. ═══ 12.3.12. Key Position ═══ Format: position=nnnn Range: 1 through value specified for Record Length element (up to 4088) Commands: CREATE, INDEX, SINDEX The Key Position element indicates the position of the key segment in the record. The key position value must be at least 1 and cannot exceed the value you specified for the Record Length element. ═══ 12.3.13. Key Length ═══ Format: length=nnn Range: 1 through limit determined by key type Commands: CREATE, INDEX, SINDEX The Key Length element defines the length of the key or key segment field. The value you specify here cannot exceed the limit dictated by the key type, which the Key Type element specifies. The key length must be an even number if the key is an unsigned binary key type. The total of the key's length and starting position cannot exceed the file's defined record length. ═══ 12.3.14. Duplicate Key Values ═══ Format: duplicates= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Duplicate Key Values element specifies whether more than one record in the file can contain the same value for this key field. Specify y if you want to allow duplicate values for the key field; otherwise, specify n. Note: If you define duplicate key values for one segment of a segmented key, you must define duplicate key values for every segment of that key. For a segmented key that does not allow duplicates, the segments may contain duplicates between multiple records only if the key value is unique for each record. ═══ 12.3.15. Modifiable Key Values ═══ Format: modifiable= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Modifiable Key Values element specifies whether the key value can be modified during updating. Specify y if you want the values for this key to be modifiable; otherwise, specify n. Note: If you define modifiable key values for one segment of a segmented key, you must define modifiable key values for every segment of that key because the key, as a whole, is modifiable. ═══ 12.3.16. Key Type ═══ Format: type=validBtrieveKeyType Range: Not applicable Commands: CREATE, INDEX, SINDEX The Key Type element specifies the File Manager data type for the key. This element determines how the File Manager sorts the bytes specified for this key segment. The File Manager does not perform any validation on the data inserted. You can specify the entire word (as in string) or just the first three letters of the word (as in str for string). The File Manager key types are: string and unsigned binary. ═══ 12.3.17. Alternate Collating Sequence ═══ Format: alternate= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Alternate Collating Sequence element is optional, and is only supported for files created using the CREATE command. This element allows you to specify one or more alternate collating sequences for a given file. An alternate collating sequence specifies whether the File Manager will sort a key by a collating sequence other than the standard ASCII sequence. You can specify a different alternate collating sequence for each key. However, each segment of the key can have only one alternate collating sequence. Alternate collating sequences are valid only for the string key type. If you want the key to take advantage of an alternate collating sequence, specify y. Otherwise, either specify n or omit this element from the description file. If a file is created with an alternate collating sequence, you should specify N in the Alt key segment field in the FCT. This avoids conflicts with the EBCDIC sequence used by CICS. ═══ 12.3.18. Manual Key ═══ Format: manual= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Manual Key element is optional. It specifies that the key or key segment you are defining is manual. A manual key is a modified form of the null key and can be used to exclude particular records from the index. Manual keys have all the attributes of a null key with one exception: in a manual key, if every byte of one segment of the key contains the null value, the File Manager excludes the key from the index even if other segments do not contain this null value. If you define a segment as manual, you must define a null value for that segment, and you must define all other segments of that key as manual; however, the null values you define for each segment can be different. To create a manual key or key segment, specify y; otherwise, specify n or omit this element from your description file. ═══ 12.3.19. Null Key ═══ Format: null= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Null Key element specifies whether the key you are defining has a null value. You can include the Null Key element in a description file for the INDEX command. However, to maintain consistent formats for the CREATE, INDEX, and SINDEX description files, INDEX disregards any null value you specify. If you define a null value for one segment of a segmented key, you must define a null value for every segment of that key; however, the null values you define for each segment can be different. Specify y if you want to define a null value for this key. Otherwise, specify n. ═══ 12.3.20. Null Key Value ═══ Format: value=nn Range: Any 1-byte hexadecimal value Commands: CREATE, INDEX, SINDEX The Null Key Value element specifies the null character value (in hexadecimal) for the key. Typical null values are X'20' (blank) and X'00' (binary zero). Include this element only if you defined the key as allowing null values. If you specify n for both the Null Key element and the Manual Key element, the Null Key Value element is not required in the description file. ═══ 12.3.21. Segmented Key ═══ Format: segment= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Segmented Key element specifies whether the key you are defining has any more segments. Specify y if the key has another segment. Specify n if you are defining either a nonsegmented key or the last segment of a segmented key. ═══ 12.3.22. Alternate Collating Sequence Filename/ID ═══ Format: name=sequenceFile or countryid=nnn codepageid=nnn Range: Any valid, fully qualified pathname; or a valid country ID and code page ID; or -1 (the default) Commands: CREATE, INDEX, SINDEX The Alternate Collating Sequence Filename/ID element specifies the pathname of the file that contains an alternate collating sequence for the file you are creating. You can include up to 256 bytes of directory levels in the pathname (plus the filename). If you specified n for the Alternate Collating Sequence element for every key, do not include this element in your description file. If you specified y for the Alternate Collating Sequence element for a key, you must supply either an alternate collating sequence filename or a country ID and a code page ID. If you want all the keys in the file to use the same alternate collating sequence filename, you can either specify this element as the last element in the description file or specify the alternate collating sequence name for each key. If you want to use different alternate collating sequences, you must specify this element for each key that uses an alternate collating sequence. You can specify only one alternate collating sequence per key, and each segment of the key should have an alternate= and name= pair. To use an alternate collating sequence ID, you must specify countryid=nnn and codepageid=nnn. Use a valid country ID and code page ID. If you want to use the current locale, specify countryid=-1 and codepageid= -1. The first 265 bytes of an alternating collating sequence file contain the definition of a collating sequence other than the standard ASCII sequence. If you want to create an alternate collating sequence file, generate a file in the format that Alternate Collating Sequence File Format specifies. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 7. Alternate Collating Sequence File Format │ ├─────────┬─────────┬──────────────────────────────────────────────────────────┤ │ OFFSET │ LENGTH │ DESCRIPTION │ ├─────────┼─────────┼──────────────────────────────────────────────────────────┤ │ 0 │ 1 │ Signature byte. This byte should always contain the │ │ │ │ value X'AC'. │ ├─────────┼─────────┼──────────────────────────────────────────────────────────┤ │ 1 │ 8 │ An 8-byte name that uniquely identifies the alternate │ │ │ │ collating sequence to the File Manager. │ ├─────────┼─────────┼──────────────────────────────────────────────────────────┤ │ 9 │ 256 │ A 256-byte table containing the sort value for every │ │ │ │ character. Store the value for each sort character at │ │ │ │ the offset corresponding to the character's represen- │ │ │ │ tation in the ASCII collating sequence. For example, to │ │ │ │ sort the character A as something other than X'41', │ │ │ │ store the new sort value at offset X'41' in the table. │ └─────────┴─────────┴──────────────────────────────────────────────────────────┘ For example, assume you want to insert a character with a X'5D' between the letters U (X'55') and V (X'56') in your sequence. In this case, byte X'5D' in the sequence should contain the value X'56', and bytes X'56' through X'5C' in the sequence should contain the values X'57' through X'5D'. ═══ 13. Printing and ordering books ═══ The CICS for OS/2 books can be printed on a PostScript printer directly from the CD-ROM, or you can purchase printed copies from IBM. ═══ 13.1. Understanding the book file names ═══ The PostScript books are in the PSBOOKS subdirectory on the CD-ROM. This subdirectory contains both US English and translated books, you therefore need to understand the file naming convention we have used for the books. File names are PPPVLBnn, where: PPP Library prefix: FAA CICS for OS/2 and Transaction Server CCL CICS Clients DFH CICS Family V The version of the product components: D Transaction Server and CICS for OS/2 A CICS Clients Z CICS Family books L A one-character language code, A for US English, see Using language codes in file names B A one-character book identifier, in the range A-Z, 0-9 (9 is used for BookManager bookshelf and bookindex) nn File maintenance level The file type for PostScript books is .PS. For example, the US English version of the CICS for OS/2 Installation book is FAADAA00.PS: the same book in French is FAADFA00.PS. ═══ 13.2. Using language codes in file names ═══ Some of the books on the CD-ROM have been translated and these are identified by the fifth character in the file name. Arabic and Hebrew do not have codes assigned. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 8. Transaction Server Language Codes Used in File Names │ ├───────────────────────────┬───────────┬───────────────────────────┬──────────┤ │ LANGUAGE │ CODE │ LANGUAGE │ CODE │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ Arabic │ │ Italian │ I │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ Brazilian Portuguese │ B │ Japanese │ J │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ Chinese Simplified │ Z │ Korean │ K │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ Chinese Traditional │ T │ Norwegian │ N │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ Czech │ 1 │ Polish │ Y │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ Danish │ D │ Portuguese │ P │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ Dutch │ H │ Russian │ 5 │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ Finnish │ O │ Spanish │ S │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ French │ F │ Swedish │ V │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ German │ G │ Thai │ 4 │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ Greek │ Q │ Turkish │ X │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ Hebrew │ │ US English │ A │ ├───────────────────────────┼───────────┼───────────────────────────┼──────────┤ │ Hungarian │ 0 │ │ │ └───────────────────────────┴───────────┴───────────────────────────┴──────────┘ Note: The language code used by Transaction Server may not be the same as that used by other IBM software servers, and its position in the file name may also be different. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 9. Transaction Server PostScript Books and File Names │ ├─────────────────────────────────────────────────┬───────────────────┬────────┤ │ BOOK TITLE │ FILE NAME │ PAGES │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ Transaction Server Up and Running! │ FAADAI │ 95 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS for OS/2 Installation │ FAADAA │ 90 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS for OS/2 Customization │ FAADAB │ 300 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS for OS/2 Operation │ FAADAC │ 220 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS for OS/2 Reference Summary │ FAADAD │ 60 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS for OS/2 Intercommunication │ FAADAE │ 210 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS for OS/2 Problem Determination │ FAADAF │ 250 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS for OS/2 Performance │ FAADAJ │ 75 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS for OS/2 Application Programming │ FAADAG │ 680 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS for OS/2 Messages and Codes │ FAADAH │ 200 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS Clients Administration │ CCLAAA │ 220 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS Clients Messages and Codes │ CCLAAB │ 75 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS Clients Gateways │ CCLAAC │ 40 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS Family: API Structure │ DFHZAC │ 310 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS Family: Client/Server Programming │ DFHZAD │ 180 │ ├─────────────────────────────────────────────────┼───────────────────┼────────┤ │ CICS Family: Intercommunication │ DFHZAF │ 90 │ ├─────────────────────────────────────────────────┴───────────────────┴────────┤ │ NOTE: The above list of File names does not include the 2-digit suffix. │ └──────────────────────────────────────────────────────────────────────────────┘ ═══ 13.3. Printing postScript manuals ═══ You can print a PostScript book from the File Manager using drag and drop, if you have a printer icon on your desktop that represents a PostScript printer: 1. Identify the file name of the book for your language 2. Double click on the Drives icon 3. Double click on your CD-ROM drive icon 4. Double click on the PSBOOKS directory 5. Drag the file you want to print to your PostScript printer icon Alternatively, to print a PostScript book from the OS/2 command prompt: 1. Identify the file name of the book, in your language 2. Go to an OS/2 command prompt 3. Switch to the drive letter of the CD-ROM 4. Type cd psbooks and press Enter 5. Use the copy command to copy the file to your PostScript printer You will need to include the file name suffix (nn) which is not shown in Transaction Server PostScript Books and File Names. All the FAA prefix books are 00, you can check the other books by issuing the dir command against the PSBOOKS directory. ═══ 13.4. Ordering books ═══ You can use the order numbers shown in Publications to order publications through your IBM representative or the IBM branch office serving your locality. In the United States and Canada, you can also order publications by dialing 1-800-879-2755. ═══ 14. Viewing online information ═══ CICS for OS/2 has three types of online information:  Product help  IPF (information presentation facility) books  BookManager books ═══ 14.1. Viewing product help ═══ CICS for OS/2 has two types of online help: Help for panels When you are looking at a CICS for OS/2 panel, the help gives you information about that panel. The information shown first is very specific, such as maximum values allowed in fields; subsequent panels give more general background information. If you are using an interactive panel, more help may be available on the panel help. Help for messages and abend codes Each CICS for OS/2 message and abend code has help. This explains the message and tells you what to do next. The CICS Clients do not have help. ═══ 14.2. Accessing help ═══ You can get CICS for OS/2 help by doing one of the following:  Selecting the Help action on a panel  Pressing the F1 function key on a panel  Running the CICS transaction CHLP: At a CICS terminal, type CHLP followed by the panel identifier, message number, or abend code. For example: CHLP FAADCT1 (panel) CHLP FAA0131E (message) CHLP FAA0131 (message without prefix) CHLP 0131 (message without prefix and suffix) CHLP AEIN (abend code) The panel identifier is the alphanumeric ID displayed in the top left-hand corner of the panel. You can use the CHLP transaction from either a server or a client.  Issuing the OS/2 CICSHELP command: This is similar to using CHLP. At an OS/2 command prompt, type CICSHELP followed by the panel identifier, message number, or abend code. You can use CICSHELP from a server, but not from a client. ═══ 14.3. Exiting from help ═══ Press F3 to exit from a help panel, CHLP, and CICSHELP. ═══ 14.4. Relocating the help and message text files ═══ The environment variable CICSTEXT defines the location of the message text and online help files. The message text file is FAAMGFMG and the help files are FAAHLFT1, FAAHLFT2, and FAAHLFT3. See the CICS for OS/2 Customization book for information about setting the path. ═══ 14.5. Viewing IPF books ═══ The IPF viewer contains powerful search facilities and because all the books within CICS for OS/2 are built with hypertext links to each other, you can easily follow the cross references from one book to another. You choose whether or not to install the IPF books during installation, as described in the CICS for OS/2 Installation book. This means the books are readily available on your desktop. The CICS for OS/2 books and CICS Family books are in the CICS for OS/2 Manuals folder. CICS Client for OS/2 books are in the IBM CICS Client for OS/2 folder, and CICS Client for Windows books are in the IBM CICS Client for Windows folder. If you installed a language other than US English, you may have IPF books in that language too. Although only some of the books are likely to have been translated, you will still have a full set of books in the folder. This allows you to hyperlink between the translated books and the US English books. You cannot tell which books have been translated until you open them. To view an IPF book, open the CICS for OS/2 Manuals folder and double-click on the BOOK icon for the book you want to read. Once inside a book, you will be able to hyperlink to the other books in the library by double-clicking in the highlighted fields. To return from a book you have linked to, just close that book, and you are returned to the book you were previously viewing. To search for specific information, click on the search push button and enter your search criteria. A panel will be presented with all search matches. Click on the one you wish to view. ═══ 14.6. Viewing BookManager Books ═══ BookManager books are similar to IPF books, but they can be viewed on both workstations and mainframes, using the BookManager Library Reader and READ products. You can read the books directly from the Transaction Server CD-ROM or you can install them on your hard disk. The CICS for OS/2 bookshelf name for the US English books is FAADA900., The fifth character in the name, which is A, identifies this as English. If books are translated there will be a different fifth character in the file name, for example, the French bookshelf would beFAADF900. The language codes used in the file name are shown in Using language codes in file names. The books (.BOO) and bookshelf search index files (.BKI) are in the \BOOKS subdirectory on the CD-ROM, and the bookshelf files (.BKS) are in the \SHELVES subdirectory. Note: The Transaction Server Up and Running! book is not provided in BookManager format. The BookManager books are maintained on IBM Collection Kit CD-ROMs. These are produced approximately three times a year, and are obtainable through your normal IBM channel. ═══ 14.7. Getting Started ═══ To use BookManager books on a workstation with a CD-ROM drive (or attached to a network equipped with a CD-ROM drive), you must use one of these products:  IBM Library Reader/2 (provided on the Transaction Server CD-ROM)  IBM BookManager READ/2 (Program No. 5601-454) The following instructions assumes you are using IBM Library Reader/2. There are several BookManager books on the CD-ROM about the Bookmanager Library Reader programs. They are in the AB0RWT bookshelf. ═══ 14.8. Installing or ipdating the IBM online library ═══ The Transaction Server CD-ROM includes a library installation and setup program to help you set up an IBM Online Library. The program installs or updates the IBM Library Reader program on your hard disk and updates your workstation so that you can access the softcopy files. If you already have IBM Library Reader or BookManager READ/2 installed and you are adding a new collection of IBM online books, you should still run the library installation program to set up your book and bookshelf search path so that you can access the softcopy files. For information on how to transfer the IBM Library Reader program to workstations without CD-ROM drives, see IBM Online Library: Getting Started and Managing the Library EZ2GSB in the AB0RWT bookshelf. ═══ 14.9. Installing or updating from a CD-ROM ═══ The IBM Library Reader installation program installs the IBM Library Reader program on your hard disk and updates your book and bookshelf search path to include the books and bookshelves in the collection. To run the installation program: 1. Insert the CD-ROM into the drive 2. Go to an OS/2 command prompt 3. Switch to the drive letter of the CD-ROM For example, if your CD-ROM drive is E, type e: and press Enter 4. Change to the CD-ROM directory that contains the IBM Library Reader program, type cd ez2inst and press Enter 5. To start the IBM Library Reader installation program, type install, and press Enter Panel 1 should appear on your screen 6. After reading panel 1, press PgDn 7. On Panel 2, make a selection that applies to your workstation. Type the number of your selection if you need to, and press PgDn to continue 8. On Panel 3: If you need help with an item, move the cursor to it, and press F1 for more information. a. Type the drive letters for any drives on which you plan to put IBM books or collections from the IBM Online Library. The drives you can select are listed at the top of the screen. You should include your CD-ROM drives and any hard disks on which you plan to store softcopy files b. Make sure that the directory name is correct c. Make sure that the configuration file or profile name is correct d. When you are satisfied that this panel is correct, press F10 to install the IBM Library Reader program or to update your IBM Library Reader 9. When the installation program is finished, the instructions on the screen tell you either to shut down and restart your system or to start the IBM Library Reader You will have to restart if CONFIG.SYS was updated ═══ 14.10. Opening the IBM online library ═══ After you finish with the IBM Library Reader installation program, you can open the IBM Online Library and use the IBM Library Reader program to list the bookshelves on the CD-ROM and select and view online books. ═══ 14.11. Listing bookshelves when opening an online library ═══ 1. Open the IBM Online Library folder and select the library you want Or, go to an OS/2 command prompt and type readibm /ds to start Library Reader 2. When the IBM Library Reader starts, it displays a WELCOME panel Press ENTER to remove the WELCOME panel from the screen; a list of all available bookshelves is displayed The Transaction Server bookshelf for US English books is FAADA900. Note: The fifth character identifies the language for the bookshelf. There may be books in your language, see Using language codes in file names for the list of language codes. The list of IBM bookshelves may include:  All the IBM bookshelves on any other drives to which you have access  All your personal bookshelves, if you have customized the IBM Online Library and created your own personal bookshelves on your fixed disk Depending on how you customized your bookshelves, the list may only show your personal bookshelves. For more information on customizing bookshelves, see the book IBM Online Library: Getting Started and Managing the Library, EZ2GSB in the AB0RWT bookshelf. 3. You are now ready to view the books on the CD-ROM. Note: You should be aware that certain terms and conditions apply to using and distributing the IBM Libary Reader Programs. These terms and conditions are in the following files in the root directory on the CD-ROM: PLALRENG.AGR SCRTENG.AGR BOOKENG.AGR These are plain text files, you can browse them and print them. ═══ 15. Glossary ═══ This glossary defines special CICS for OS/2 terms used in this book; terms used in a mainframe CICS installation, but which might nevertheless be unfamiliar; terms used with workstations; and words used with other than their everyday meaning. If you cannot find the word you are looking for, try the IBM Dictionary of Computing. ═══ 15.1. A ═══ ═══ 15.1.1. action bar ═══ action bar A bar across the first line of a panel that shows the actions you can perform from that panel. An action is selected by moving the cursor to the required action and pressing Enter. ═══ 15.1.2. alternate index ═══ alternate index A collection of index entries organized by an alternate key; it gives an alternate directory for finding records. ═══ 15.1.3. APPC ═══ APPC Advanced program-to-program communication. An implementation of the SNA/SDLC LU6.2 protocol that allows interconnected systems to communicate and share the processing of programs. Protocol used by CICS for OS/2 to communicate with a mainframe CICS system. It may also be used between CICS for OS/2 systems connected in a LAN. ═══ 15.1.4. application group ═══ application group See group. ═══ 15.1.5. ASCII ═══ ASCII American National Standard Code for Information Interchange. A character set consisting of 7-bit coded characters, used on programmable workstations. ═══ 15.1.6. asynchronous processing ═══ asynchronous processing 1. A form of function shipping in which interval control START requests are shipped. It enables a CICS transaction to initiate a transaction in a remote system and to pass data to it. `Asynchronous' means there is no time correlation between requests and replies. 2. Any form of processing in which a calling process does not wait for the result of the call before continuing execution. ═══ 15.1.7. ATI ═══ ATI See automatic transaction initiation. ═══ 15.1.8. autoinstall ═══ autoinstall A facility that enables terminal definitions to be created automatically in the TCT on request. The definition is deleted when the terminal is logged off. ═══ 15.1.9. automatic transaction initiation (ATI) ═══ automatic transaction initiation (ATI) A facility of intrapartition transient data. You can specify that when data is sent to an intrapartition destination and the number of entries reaches a predefined level, a transaction is automatically started to process the data in the queue. ═══ 15.2. B ═══ ═══ 15.2.1. backout ═══ backout The process of canceling changes made by a transaction to a file following the failure of that transaction. ═══ 15.2.2. backup file ═══ backup file FAAAEFBU. The system file that holds a copy of applications exported using the CAEX transaction. ═══ 15.2.3. BMS ═══ BMS Basic mapping support. A facility that handles data streams to and from a terminal. It provides device and format independence for application programs. ═══ 15.2.4. BMSMAP ═══ BMSMAP An environment variable used to set the path to the map set master file in CICS applications (see environment variable). ═══ 15.2.5. BMS master file ═══ BMS master file The file that holds the translated maps. It is created by the BMS translator command, CICSMAP. ═══ 15.3. C ═══ ═══ 15.3.1. CADL ═══ CADL The application delete transaction. ═══ 15.3.2. CAEX ═══ CAEX The application export transaction. ═══ 15.3.3. CAIM ═══ CAIM The application import transaction. ═══ 15.3.4. CECI ═══ CECI The command level interpreter transaction. ═══ 15.3.5. CEDA ═══ CEDA The resource definition transaction. ═══ 15.3.6. CEDF ═══ CEDF The transaction used to start the Execution Diagnostic Facility. ═══ 15.3.7. CEMT ═══ CEMT The master terminal transaction used to manage system resources. ═══ 15.3.8. centralized processing ═══ centralized processing Processing in which the application is processed on a central processor, which users access using geographically remote, nonprogrammable, terminals. Contrast with distributed processing. ═══ 15.3.9. CESF ═══ CESF The sign-off transaction. ═══ 15.3.10. CESN ═══ CESN The sign-on transaction. ═══ 15.3.11. CETR ═══ CETR The trace transaction. ═══ 15.3.12. CI ═══ CI See control interval. ═══ 15.3.13. CICSCCMP ═══ CICSCCMP The command file for compiling 32-bit C programs. ═══ 15.3.14. CICSCLNK ═══ CICSCLNK The command file for link-editing 32-bit C programs. ═══ 15.3.15. CICSCOMP ═══ CICSCOMP The command file for compiling COBOL programs. ═══ 15.3.16. CICSCTCL ═══ CICSCTCL The command file for translating, compiling, and link-editing 32-bit C programs. ═══ 15.3.17. CICSCTRN ═══ CICSCTRN The command file for translating C programs. ═══ 15.3.18. CICSCEXI ═══ CICSCEXI The command file for compiling and link-editing C user exits. ═══ 15.3.19. CICSEXI ═══ CICSEXI The command file for compiling and link-editing COBOL user exits. ═══ 15.3.20. CICSLINK ═══ CICSLINK The command file for link-editing COBOL programs. ═══ 15.3.21. CICSPCLK ═══ CICSPCLK The translate, compile, and link-edit program command file (PL/I). ═══ 15.3.22. CICSPCMP ═══ CICSPCMP The command file for translating and compiling PL/I programs. ═══ 15.3.23. CICSPLNK ═══ CICSPLNK The command file for linking PL/I programs. ═══ 15.3.24. CICSMAP ═══ CICSMAP The command file for translating map sets. ═══ 15.3.25. CICSRD ═══ CICSRD An environment variable that is set to the name of the CICS for OS/2 resource control file. ═══ 15.3.26. CICSRUN ═══ CICSRUN The command file for starting CICS for OS/2. ═══ 15.3.27. CICSTCL ═══ CICSTCL The command file for translating, compiling, and link-editing COBOL programs. ═══ 15.3.28. CICSTEXT ═══ CICSTEXT An environment variable used to set the path to the message text file and the online help files (see environment variable). ═══ 15.3.29. CICSFMT ═══ CICSFMT The command file for formatting and printing the trace file. ═══ 15.3.30. CICSTRAN ═══ CICSTRAN The command file for translating COBOL programs. ═══ 15.3.31. CICSTRL ═══ CICSTRL An environment variable used to set the path for translator error messages in C applications (see environment variable). ═══ 15.3.32. CICSWRK ═══ CICSWRK An environment variable used to set the path to CICS for OS/2 run-time application and system code. All programs that CICS for OS/2 requires while it is running should be in this path (see environment variable). ═══ 15.3.33. client ═══ client In a CICS for OS/2 system the client machines have only a subset of the CICS for OS/2 code, but via the LAN can access a CICS for OS/2 server machine to perform transaction processing. Clients can run under OS/2, DOS, Microsoft Windows, or on the Apple Macintosh. ═══ 15.3.34. COBCPY ═══ COBCPY An environment variable used to set the path to the directory containing map sets and other copy books for input to the program translator in COBOL applications (see environment variable). ═══ 15.3.35. COBDIR ═══ COBDIR An environment variable used to set the path to the COBOL system directory in COBOL applications (see environment variable). ═══ 15.3.36. COBWRK ═══ COBWRK An environment variable used to set the path to the directory where output from the program translator is to be placed in COBOL applications (see environment variable). ═══ 15.3.37. command ═══ command In CICS, an instruction similar in format to a high-level language instruction. It includes the verb EXECUTE (or EXEC). In CICS for OS/2, a command is used more generally to mean the name of a command file (for example, CICSTRAN), as well as an EXEC CICS instruction. ═══ 15.3.38. command file ═══ command file A file with the extension .CMD in OS/2 The command is issued by entering the name of the command file at the OS/2 command prompt. Contrast with transaction. ═══ 15.3.39. common work area (CWA) ═══ common work area (CWA) A work area that can be accessed by any transaction in the CICS for OS/2 system. ═══ 15.3.40. COMMAREA ═══ COMMAREA A communication area that is used for passing data both between programs within a transaction and between transactions. ═══ 15.3.41. control program ═══ control program The main CICS for OS/2 program that sets up the workstation CICS environment and runs the application programs. ═══ 15.3.42. control table ═══ control table In CICS, a storage area used to describe or define the configuration or operation of the system. ═══ 15.3.43. control interval (CI) ═══ control interval (CI) A fixed-length area of direct access storage in which the file manager (VSAM on a mainframe CICS system) stores records and creates distributed free space. Also, in a key-sequenced file, the set of records pointed to by an entry in the sequence-set index record. The control interval is the unit of information that the file manager transmits to and from direct access storage. A control interval always comprises an integral number of physical records. ═══ 15.3.44. conversion template ═══ conversion template You define conversion templates for each resource type: together, they make up the conversion table that is used to convert workstation ASCII data into mainframe EBCDIC data, and vice versa. ═══ 15.3.45. CPOP ═══ CPOP The transaction for controlling the PL/I Interactive Test facility. ═══ 15.3.46. CQIT ═══ CQIT The shutdown transaction. ═══ 15.3.47. CSCA ═══ CSCA The view and delete map sets transaction. ═══ 15.3.48. CSFE ═══ CSFE The storage control transaction. ═══ 15.3.49. CWA ═══ CWA See common work area. ═══ 15.3.50. CWRK ═══ CWRK An environment variable used to set the path to the directory where output from the C program translator is to be placed (see environment variable). ═══ 15.4. D ═══ ═══ 15.4.1. data file ═══ data file See file. ═══ 15.4.2. data set ═══ data set See file. ═══ 15.4.3. data table ═══ data table A shared data area that is accessible to all tasks. Data table file names have the extension .DAT. ═══ 15.4.4. DBCS ═══ DBCS See double-byte character set. ═══ 15.4.5. DCT ═══ DCT See destination control table. ═══ 15.4.6. destination control table (DCT) ═══ destination control table (DCT) A table describing each of the transient data destinations used in the CICS for OS/2 system. ═══ 15.4.7. DFHAID.CBL ═══ DFHAID.CBL Attention identifier list, for use with COBOL programs. A copybook containing the symbolic names for the attention identifiers. It allows you to test, for example, whether Enter had been pressed. ═══ 15.4.8. DFHAID.H ═══ DFHAID.H Attention identifier list, for use with C programs. A header file containing the symbolic names for the attention identifiers. It allows you to test, for example, whether Enter had been pressed. ═══ 15.4.9. DFHAID.INC ═══ DFHAID.INC Attention identifier list, for use with PL/I programs. An include file containing the symbolic names for the attention identifiers. It allows you to test, for example, whether Enter had been pressed. ═══ 15.4.10. DFHBMSCA.CBL ═══ DFHBMSCA.CBL Attribute and printer control character list, for use with COBOL programs. A copybook containing the symbolic names for the various combinations of attributes and control characters. ═══ 15.4.11. DFHBMSCA.H ═══ DFHBMSCA.H Attribute and printer control character list, for use with C programs. A file containing the symbolic names for the various combinations of attributes and control characters. ═══ 15.4.12. DFHBMSCA.INC ═══ DFHBMSCA.INC Attribute and printer control character list, for use with PL/I programs. A file containing the symbolic names for the various combinations of attributes and control characters. ═══ 15.4.13. DFHCCNV and DFHUCNV ═══ DFHCCNV and DFHUCNV The programs that handle EBCDIC-to-ASCII and ASCII-to-EBCDIC conversion in the mainframe system. ═══ 15.4.14. dialog ═══ dialog The communication between a person and a computer. ═══ 15.4.15. distributed processing ═══ distributed processing Processing in which application transaction programs distributed among interconnected processors cooperate to perform applications for end users of a network. Contrast with centralized processing. ═══ 15.4.16. distributed program link (DPL) ═══ distributed program link (DPL) An extension to the CICS application programming interface (API) that allows a program to link to another program on a remote system. ═══ 15.4.17. distributed transaction processing (DTP) ═══ distributed transaction processing (DTP) A facility enabling a CICS transaction to communicate with a transaction running in another system. Communication between the transactions is synchronous, which means that a single session is acquired and held by the two transactions. ═══ 15.4.18. double-byte character set ═══ double-byte character set A character set that requires two bytes to represent all the characters in it. Used for Japanese and other Asian languages. ═══ 15.4.19. downloading ═══ downloading Transferring programs or data from a file on the remote system to a file on the workstation using an offline utility. ═══ 15.4.20. DTB ═══ DTB See dynamic transaction backout. ═══ 15.4.21. DTP ═══ DTP See distributed transaction processing. ═══ 15.4.22. dynamic transaction backout (DTB) ═══ dynamic transaction backout (DTB) A CICS feature that allows the effects of an abnormally terminating transaction (up to the last syncpoint) to be reversed immediately, while the rest of CICS continues normally. ═══ 15.5. E ═══ ═══ 15.5.1. EBCDIC ═══ EBCDIC Extended Binary-Coded Decimal Interchange Code. The code used by medium-to-large IBM System/390 mainframes. ═══ 15.5.2. ECI ═══ ECI See external call interface. ═══ 15.5.3. EDF ═══ EDF See Execution Diagnostic Facility. ═══ 15.5.4. EIB ═══ EIB See Execution Interface Block. ═══ 15.5.5. emulator, emulation program ═══ emulator, emulation program A program that allows a host system to communicate with a workstation in the same way as it would with the emulated terminal. In CICS for OS/2, the TR emulator allows CICS for OS/2 client workstations to run CICS transactions that use 3270 data flows. ═══ 15.5.6. entry-sequenced data set (ESDS) ═══ entry-sequenced data set (ESDS) A file in which the records are loaded without respect to their contents. The relative record byte addresses of the records cannot change. Records are retrieved and stored by address access, and new records are added at the end of the file. ═══ 15.5.7. environment variable ═══ environment variable A variable used to set a directory path for the files used in a CICS application. ═══ 15.5.8. EPI ═══ EPI See external presentation interface. ═══ 15.5.9. ESDS ═══ ESDS See entry-sequenced data set. ═══ 15.5.10. ETI ═══ ETI See external transaction initiation. ═══ 15.5.11. EXEC (EXECUTE) statement ═══ EXEC (EXECUTE) statement See command. ═══ 15.5.12. Execution Diagnostic Facility (EDF) ═══ Execution Diagnostic Facility (EDF) A facility that helps you to debug an application by stepping through its CICS commands. You can change values in the application while it is running. To start EDF, you use the CEDF transaction. ═══ 15.5.13. Execution Interface Block (EIB) ═══ Execution Interface Block (EIB) A control block associated with a CICS task, and used for direct communication between command-level programs and CICS. ═══ 15.5.14. external call ═══ external call A facility that allows an application to gain access to CICS for OS/2 data with a subroutine call. ═══ 15.5.15. external call interface (ECI) ═══ external call interface (ECI) A facility that allows a non-CICS for OS/2 program to run a CICS for OS/2 program. Data is exchanged in a COMMAREA as for normal CICS interprogram communication. ═══ 15.5.16. external presentation interface (EPI) ═══ external presentation interface (EPI) A facility that allows a non-CICS program to appear to CICS for OS/2 as one or more standard 3270 terminals. 3270 data can be presented to the user by emulating a 3270 terminal or by using a graphical user interface. ═══ 15.5.17. external transaction initiation (ETI) ═══ external transaction initiation (ETI) A facility that allows you to start a CICS for OS/2 transaction from outside CICS for OS/2. ═══ 15.5.18. extrapartition destination ═══ extrapartition destination An extrapartition destination is a queue residing on any device that is accessible by programs outside, as well as inside, CICS for OS/2. Such a queue may be an OS/2 format file, a printer, or other serial device. ═══ 15.6. F ═══ ═══ 15.6.1. FAACSTRT.H ═══ FAACSTRT.H A header file containing the field definitions for the EIB, for use in C programs. ═══ 15.6.2. FAAPMPSM ═══ FAAPMPSM A sample program that starts a transaction from outside CICS for OS/2. See external transaction initiation. ═══ 15.6.3. FCT ═══ FCT See file control table. ═══ 15.6.4. file ═══ file A named set of records stored or processed as a unit. In CICS for OS/2, this term is synonymous with data set. ═══ 15.6.5. file control table (FCT) ═══ file control table (FCT) A table containing the characteristics of files accessed by file control. ═══ 15.6.6. function shipping ═══ function shipping The process by which data on a remote system is accessed by an application running on the local system. The process is transparent to the user of the application. ═══ 15.7. G ═══ ═══ 15.7.1. global task ═══ global task A routine that controls the running of the CICS for OS/2 system. It starts and ends processes, which run as subtasks of the global task, and sessions. It is also responsible for providing services such as temporary storage and trace facilities. ═══ 15.7.2. group ═══ group A collection of elements (programs, BMS map sets, and table entries,) that can be usefully exported together. A group normally includes all the elements that constitute one application. The group name is specified in the control table entry for an element. ═══ 15.8. H ═══ ═══ 15.8.1. header file ═══ header file In C programs, a file containing data definitions that is included in a program. ═══ 15.8.2. host ═══ host The controlling or highest level system (computer) in a data communication configuration. This is usually, but not always, a mainframe computer. ═══ 15.9. I ═══ ═══ 15.9.1. import-export file ═══ import-export file The system file to which applications are exported using the CAEX transaction, and from which they are imported using the CAIM transaction. ═══ 15.9.2. INCLUDE ═══ INCLUDE An environment variable used to set the path to the directory or directories containing header files in C applications (see environment variable). ═══ 15.9.3. include file ═══ include file In PL/I programs, a file containing data definitions that is included in a program. ═══ 15.9.4. indirect destination ═══ indirect destination An indirect destination points to another Destination Control Table (DCT) destination. ═══ 15.9.5. initialization ═══ initialization The preparation of a system, device, or program for operation. An operating system is initialized on starting up or after a system failure. Initializing CICS for OS/2 includes starting the file manager and terminal emulator. The necessary commands are supplied in a command file called CICSRUN that you can run by typing its name at the OS/2 command prompt. ═══ 15.9.6. interception point ═══ interception point In the Execution Diagnostic Facility, a point at which execution is interrupted to allow the display of program information (see Execution Diagnostic Facility). ═══ 15.9.7. intrapartition destination ═══ intrapartition destination A queue of transient data used subsequently as input data to another task within CICS for OS/2. ═══ 15.10. K ═══ ═══ 15.10.1. key-sequenced data set (KSDS) ═══ key-sequenced data set (KSDS) A file in which the records are loaded in key sequence and controlled by an index. See also alternate index. ═══ 15.10.2. KSDS ═══ KSDS See key-sequenced data set. ═══ 15.11. L ═══ ═══ 15.11.1. LAN ═══ LAN See local area network. ═══ 15.11.2. LIB ═══ LIB An environment variable used to set the path to the directory or directories containing the run-time system library (see environment variable). ═══ 15.11.3. local ═══ local Pertaining to the system, program, or device being described, as opposed to other systems, programs, or devices that are further away. Contrast with remote. ═══ 15.11.4. local area network (LAN) ═══ local area network (LAN) A network of workstations, or terminals, or both, where all the connected systems are relatively near to each other. ═══ 15.11.5. log data set buffer ═══ log data set buffer Copies of records being changed are stored in this buffer prior to the changes. The buffer is used to recover files in the event of a system failure. ═══ 15.11.6. logical unit of work (LUW) ═══ logical unit of work (LUW) A sequence of processing actions (database changes, for example) that must be completed before any of the individual actions can be regarded as committed. When changes are committed (by successful completion of the LUW and recording of the syncpoint on the system log), they do not need to be backed out after a subsequent failure of the task or system. The end of an LUW is marked in a transaction by a syncpoint, issued either by the application or by CICS at the end of task. In the absence of user syncpoints, the entire task is an LUW. ═══ 15.11.7. log off ═══ log off 1. To end a session. 2. To request that a session be ended. 3. See also sign off. ═══ 15.11.8. log on ═══ log on 1. To initiate a session. 2. To initiate a session between an application program and a logical unit. 3. See also sign on. ═══ 15.11.9. LUW ═══ LUW See logical unit of work. ═══ 15.11.10. LU6.2 ═══ LU6.2 See APPC. ═══ 15.12. M ═══ ═══ 15.12.1. message text file ═══ message text file The file holding the text of all CICS for OS/2 error messages. ═══ 15.12.2. no-op command ═══ no-op command In the Execution Diagnostic Facility, a command whose execution you have suppressed. ═══ 15.13. O ═══ ═══ 15.13.1. OS/2 ═══ OS/2 IBM Operating System/2. The multitasking operating system designed for the Personal System/2 range of workstations that have the Intel 80386 or 80486 processors. ═══ 15.14. P ═══ ═══ 15.14.1. PATH ═══ PATH An environment variable used to set the path for external commands that are outside your current directory (see environment variable). ═══ 15.14.2. PCT ═══ PCT See program control table. ═══ 15.14.3. PNA ═══ PNA See Programmable Network Access. ═══ 15.14.4. post-initialization program ═══ post-initialization program Program FAAOISO4 that is called immediately after initialization. It is called once for each terminal and once for each background task. This program can be customized. ═══ 15.14.5. PPT ═══ PPT See processing program table. ═══ 15.14.6. process ═══ process 1. a nonfacility task run as a background task. Includes printer tasks. 2. In OS/2, a collection of system resources including one or more threads. ═══ 15.14.7. processing program table (PPT) ═══ processing program table (PPT) A table defining the application programs that can be run under CICS for OS/2. ═══ 15.14.8. program control table (PCT) ═══ program control table (PCT) A table defining the transactions that can be processed by the system. ═══ 15.14.9. Programmable Network Access (PNA) ═══ Programmable Network Access (PNA) An IBM product for OS/2 that allows attachment of up to 40 ASCII terminals to a single PS/2 computer. The ASCII terminals are attached through Realtime Interface Coprocessor (ARTIC) adapter cards, on which software is run to perform 3270 controller-emulation functions. ═══ 15.14.10. programmable workstation ═══ programmable workstation A workstation that has its own processing capability. A CICS for OS/2 programmable workstation can be, for example, an IBM Personal System/2 computer or compatible system. ═══ 15.14.11. PS/2 ═══ PS/2 IBM Personal System/2 computer. A range of IBM multitasking interactive workstations. ═══ 15.15. R ═══ ═══ 15.15.1. RACF ═══ RACF See resource access control facility. ═══ 15.15.2. recoverable (requests) ═══ recoverable (requests) Requests on a queue or in a file that can be restored to their state at the exit of the last task or syncpoint after transaction or system failure. They are equivalent to logically recoverable requests in mainframe CICS. ═══ 15.15.3. relative record data set (RRDS) ═══ relative record data set (RRDS) A file in which each record is assigned a record number according to its relative position within the file storage space. The record number must be used to retrieve the record. ═══ 15.15.4. remote ═══ remote Pertaining to a system, program, or device that is accessed through a telecommunication line. Contrast with local. ═══ 15.15.5. remote destination ═══ remote destination A destination that exists on a remote CICS system. ═══ 15.15.6. resource access control facility (RACF) ═══ resource access control facility (RACF) An IBM-licensed program, available on mainframe systems, that provides for access control by identifying the users to the system, authorizing access to protected resources, logging the detected unauthorized attempts to enter the system, and logging the detected accesses to protected resources. ═══ 15.15.7. RRDS ═══ RRDS See relative record data set. ═══ 15.16. S ═══ ═══ 15.16.1. SAA ═══ SAA See Systems Application Architecture. ═══ 15.16.2. SBCS ═══ SBCS Single-byte character Set. A character set that requires one byte to represent all the characters in it. The term is used when the set is being compared to a double-byte character set. ═══ 15.16.3. screen switch function ═══ screen switch function A facility that enables workstation users to switch sessions by pressing the Alt + Esc keys. ═══ 15.16.4. SDLC ═══ SDLC See Synchronous Data Link Control. ═══ 15.16.5. semaphore ═══ semaphore An object used by multithreaded applications for signaling and for controlling access to serially reusable resources. ═══ 15.16.6. server ═══ server In a CICS for OS/2 system, server machines provide transaction processing facilities to the client machines on the LAN. ═══ 15.16.7. session ═══ session 1. A terminal task. 2. In OS/2, that group of processes or tasks associated with an application. ═══ 15.16.8. shared storage ═══ shared storage Storage shared between sessions and processes, the allocation of which is controlled by the global task. ═══ 15.16.9. shippable terminal ═══ shippable terminal A terminal whose definition can be shipped to another CICS system as and when the other system requires a remote definition of that terminal. ═══ 15.16.10. shutdown program ═══ shutdown program Program FAAOISPT is called after the transaction CQIT has started the shutdown process. It is called once for each terminal and once for each background task. The program can be customized. ═══ 15.16.11. sign off ═══ sign off 1. To enter a command or to select an option from a menu that instructs the system to end an interactive job. 2. To end a session at a terminal or workstation. 3. See also log off. ═══ 15.16.12. sign on ═══ sign on 1. A procedure to be followed at a terminal or workstation to establish a link to a computer. 2. To begin a session at a workstation. 3. See also log on. ═══ 15.16.13. signon table (SNT) ═══ signon table (SNT) A table containing the user IDs and passwords of CICS for OS/2 users. ═══ 15.16.14. SIT ═══ SIT See system initialization table. ═══ 15.16.15. SNT ═══ SNT See signon table. ═══ 15.16.16. SQL ═══ SQL Structured query language. ═══ 15.16.17. stop condition ═══ stop condition A specified condition for stopping the execution of a transaction that is being debugged by the Execution Diagnostic Facility. ═══ 15.16.18. Synchronous Data Link Control (SDLC) ═══ Synchronous Data Link Control (SDLC) A communications protocol for managing synchronous, code-transparent serial-by-bit information transfer over a link connection. ═══ 15.16.19. synchronous processing ═══ synchronous processing A form of processing in which a calling process waits for ═══ 15.16.20. system administrator ═══ system administrator Any person authorized to use the CEDA command. An installation can have as many system administrators as required. the result of the call to be returned before continuing execution. ═══ 15.16.21. system initialization table (SIT) ═══ system initialization table (SIT) A table containing data to control the system initialization process. ═══ 15.16.22. Systems Application Architecture (SAA) ═══ Systems Application Architecture (SAA) A set of software interfaces, conventions, and protocols that provide a framework for designing and developing applications across multiple computing environments. ═══ 15.17. T ═══ ═══ 15.17.1. TCP/IP ═══ TCP/IP Transmission Control Protocol/Internet Protocol. A communication protocol used in client-server links in a CICS for OS/2 system and also in peer-to-peer links between CICS for OS/2 systems. ═══ 15.17.2. TCS ═══ TCS See terminal control table (system entry). ═══ 15.17.3. TCT ═══ TCT See terminal control table (terminal entry). ═══ 15.17.4. TCTUA ═══ TCTUA See terminal control table user area. ═══ 15.17.5. temporary storage table (TST) ═══ temporary storage table (TST) A table describing temporary storage queues. ═══ 15.17.6. terminal control table (terminal entry) (TCT) ═══ terminal control table (terminal entry) (TCT) A table describing the logical terminals of a CICS for OS/2 system. ═══ 15.17.7. terminal control table (system entry) (TCS) ═══ terminal control table (system entry) (TCS) A table describing the remote CICS systems that are connected to CICS for OS/2. The method of connection between the systems is also defined in the TCS. ═══ 15.17.8. terminal control table user area (TCTUA) ═══ terminal control table user area (TCTUA) An area used to pass information between application programs, but only if the same terminal is associated with the application programs involved. ═══ 15.17.9. thread ═══ thread The smallest unit of processing within an OS/2 process. ═══ 15.17.10. transaction ═══ transaction A transaction must be issued from within a CICS for OS/2 session (unless you pass the details from an external program, as explained in the CICS for OS/2 Application Programming book). Contrast with command file. ═══ 15.17.11. transaction routing ═══ transaction routing For CICS for OS/2, the interactive process by which a CICS transaction on a remote CICS system can be run from the workstation. The results are returned to the workstation. ═══ 15.17.12. transaction work area (TWA) ═══ transaction work area (TWA) A work area that exists only for the duration of a transaction. Consequently, you can use it to pass data among programs executed in the same transaction but not between transactions. ═══ 15.17.13. translator ═══ translator For CICS for OS/2, a program that translates into subroutines any EXEC CICS commands in CICS application programs. ═══ 15.17.14. translator directives ═══ translator directives These are called translator options in mainframe CICS. ═══ 15.17.15. Transmission Control Protocol/Internet Protocol ═══ Transmission Control Protocol/Internet Protocol See TCP/IP. ═══ 15.17.16. TST ═══ TST See temporary storage table. ═══ 15.17.17. TWA ═══ TWA See transaction work area. ═══ 15.18. U ═══ ═══ 15.18.1. unrecoverable (requests) ═══ unrecoverable (requests) Requests on a queue or in a file that will be lost in the event of transaction or system failure. ═══ 15.19. V ═══ ═══ 15.19.1. Virtual Storage Access Method (VSAM) ═══ Virtual Storage Access Method (VSAM) An access method used on mainframe CICS systems for direct or sequential processing of fixed and variable-length records on direct access devices. The records in a VSAM file can be organized in logical sequence by a key field (key sequence), in the physical sequence in which they are written on the file (entry sequence), or by relative record number. This storage access method is emulated by the CICS for OS/2 file manager. ═══ 15.19.2. VSAM ═══ VSAM See Virtual Storage Access Method. ═══ 15.19.3. VTAM ═══ VTAM Virtual Telecommunication Access Method. ═══ 15.20. W ═══ ═══ 15.20.1. window ═══ window An area of the screen with visible boundaries through which information is displayed. A window can be smaller than or the same size as the screen. ═══ 15.20.2. working storage ═══ working storage A portion of main storage used by a COBOL program for the temporary holding of data. ═══ 15.20.3. workstation ═══ workstation The generic term for the Intel-based computer or compatible system on which CICS for OS/2 is running. ═══ 15.20.4. workstation set up (WSU) ═══ workstation set up (WSU) A table of descriptions of the workstation: screen colors and key assignments. ═══ 15.20.5. WSU ═══ WSU See workstation set up. ═══ 16. Sending your comments to IBM ═══ If you especially like or dislike anything about this book, please use one of the methods listed below to send your comments to IBM. Feel free to comment on what you regard as specific errors or omissions, and on the accuracy, organization, subject matter, or completeness of this book. Please limit your comments to the information in this book and the way in which the information is presented. To request additional publications, or to ask questions or make comments about the functions of IBM products or systems, you should talk to your IBM representative or to your IBM authorized remarketer. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate, without incurring any obligation to you. You can send your comments to IBM in any of the following ways:  By fax: - From outside the U.K., after your international access code use 44 1962 870229 - From within the U.K., use 01962 870229  Electronically, use the appropriate network ID: - IBM Mail Exchange: GBIBM2Q9 at IBMMAIL - IBMLink: WINVMD(IDRCF) - Internet: idrcf@winvmd.vnet.ibm.com Whichever you use, ensure that you include:  The publication number and title  The page number or topic to which your comment applies  Your name and address/telephone number/fax number/network ID. ═══ ═══ Depending on the type of keyboard you have, you may need to press Ctrl-Enter. ═══ ═══ These transactions are covered briefly in this topic. For more information see the CICS for OS/2 Application Programming book.