Configuring OSC Regions

This chapter describes the configuration settings of OSC regions and the steps needed to prepare them for operation.

1. Overview

Each OSC region is composed of an application server, which runs user application programs, and one or more auxiliary servers, which support the TDQ log type and the [OSC] menu in OpenFrame Manager.

Preparation for running application servers consist of the following six steps.

  1. Preparing OSC Application Server Binaries

    Prepare application server binaries and configure the server configuration file.

  2. Creating Application Server Database Tables

    Create data tables to be used in application servers.

  3. Creating Application Server Data Sets

    Create data sets to be used in application servers.

  4. Registering Application Server Resources

    Register default resources and user resources to be used in application servers.

  5. Setting Tmax Configuration File

    Register the application servers and services in the Tmax configuration file.

  6. Prepare script files required for starting and shutting down application servers.

2. Preparing OSC Application Server Binaries

The first step in preparing a new OSC application server is to create application binaries. Application server binaries can be created with the oscbuild tool. When the server binary is ready, the administrator must create and specify the configuration files that are necessary for each type of application server. For more details on configuration, refer to OSC System Settings.

2.1. Preparing Application Source Files

Prepare user source files during creation of server binaries. In OSC, you can specify or add jobs to execute through five functions.

In the user source file, the user can arbitrarily write the logic of the functions below to perform additional works necessary when the server starts up and shuts down, or add functions to start a transaction and respond to SYNCPOINT and SYNCPOINT ROLLBACK in a non-XA environment.

If no additional jobs are necessary, you don’t need to prepare any source files. Use the -f option of the oscbuild tool to specify user source files during compilation.

The following describes each function invoked in OSC.

Function Description

otpsvrinit

Invoked when the region server is started, either in a non-XA or XA environment.

otpsvcinit

Invoked when transactions are initiated in a non-XA environment.

otpsvrcommit

Invoked when SYNCPOINT is called by the user or OSC in a non-XA environment.

otpsvrrollback

Invoked when SYNCPOINT ROLLBACK is called by the user or OSC in a non-XA environment.

otpsvrdone

Invoked when the region server is shut down, either in a non-XA or XA environment.

The following shows sample sources of an OSC application server.

int otpsvrinit(int argc, char *argv[])
{
    return 0;
}

int otpsvcinit()
{
    return 0;
}

int otpsvrcommit()
{
    return 0;
}

int otpsvrrollback()
{
    return 0;
}

int otpsvrdone()
{
    return 0;
}

2.2. Compiling Source Files and Distributing Binaries

Application server binaries can be created with the oscbuild tool. The oscbuild tool allows the user to specify compilation options and the server binary name, depending on the environment on which the OSC system is running.

The following oscbuild command creates a server binary to be used in a 64-bit Linux environment. If no name is specified for the server binary, it will default to OSC00001.

$ oscbuild -o LINUX64

Once the compiler has finished, a binary named OSC00001 is created in the directory where the previous command is executed - the name can be changed later but must be 8 characters long. The binary file must then be copied to the directory designated by the APPDIR environment variable in the Tmax configuration file.

For more information about how to use the oscbuild tool, refer to OpenFrame Tool Reference Guide.

3. Creating Application Server Database Tables

You need to create a database table to store information required for operating application servers. Use the oscinit tool to create tables.

The following describes the types and features of database tables to be created.

  • Region Management Tables

    Stores information required for managing statuses of OSC regions.

    Table Name Description

    OFM_OSC_REGION_MASTER

    Stores status information of the current region, including node name, running status, server status, and so on.

    OFM_OSC_REGION_LIST

    Views the list of regions running in the domain. In a case where the region server is down, all records in the other system tables having the same region name are entirely removed.

  • System Definition Tables

    Stores resources definitions required for operating OSC systems.

    Table Name Description

    OFM_OSC_SD_GROUP

    Resource groups definitions.

    OFM_OSC_SD_CONN

    CONNECTION resource definitions.

    OFM_OSC_SD_FILE

    FILE resource definitions.

    OFM_OSC_SD_PROG

    PROGRAM resource definitions.

    OFM_OSC_SD_TYPE_TERM

    TYPETERM resource definitions.

    OFM_OSC_SD_TERM

    TERMINAL resource definitions.

    OFM_OSC_SD_TSMODEL

    TSMODEL resource definitions.

    OFM_OSC_SD_JNL_MODEL

    JOURNALMODEL resource definitions.

    OFM_OSC_SD_MAP_SET

    MAPSET resource definitions.

    OFM_OSC_SD_WEB_SVC

    WEBSERVICE resource definitions.

    OFM_OSC_SD_PIPIELINE

    PIPELINE resource definitions.

    OFM_OSC_SD_ENQ_MODEL

    ENQMODEL resource definitions.

    OFM_OSC_SD_TCPIP_SVC

    TCPIPSERVICE resource definitions.

    OFM_OSC_SD_SESSION

    SESSIONS resource definitions.

    OFM_OSC_SD_PARTITIONSET

    PARTITIONSET resource definitions.

    OFM_OSC_SD_PROFILE

    PROFILE resource definitions.

    OFM_OSC_SD_LIBRARY

    LIBRARY resource definitions.

    OFM_OSC_SD_URIMAP

    URIMAP resource definitions.

    OFM_OSC_SD_TRANS

    TRANSACTION resource definitions.

    OFM_OSC_SD_TRAN_CLASS

    TRANCLASS resource definitions.

    OFM_OSC_SD_TDQ

    TDQUEUE resource definitions.

  • Runtime System Definition Tables

    Stores resources information used while OSC server is running.

    Table Name Description

    OFM_OSC_CONN

    CONNECTION resource information.

    OFM_OSC_FILE

    FILE resource information.

    OFM_OSC_PROG

    PROGRAM resource information.

    OFM_OSC_TERM

    TERMINAL resource information.

    OFM_OSC_TSMODEL

    TSMODEL resource information.

    OFM_OSC_JNL_MODEL

    JOURNALMODEL resource information.

    OFM_OSC_MAP_SET

    MAPSET resource information.

    OFM_OSC_WEB_SVC

    WEBSERVICE resource information.

    OFM_OSC_PIPIELINE

    PIPELINE resource information.

    OFM_OSC_ENQ_MODEL

    ENQMODEL resource information.

    OFM_OSC_TCPIP_SVC

    TCPIPSERVICE resource information.

    OFM_OSC_SESSION

    SESSIONS resource information.

    OFM_OSC_PARTITIONSET

    PARTITIONSET resource information.

    OFM_OSC_PROFILE

    PROFILE resource information.

    OFM_OSC_LIBRARY

    LIBRARY resource information.

    OFM_OSC_URIMAP

    URIMAP resource information.

    OFM_OSC_TRANS

    TRANSACTION resource information.

    OFM_OSC_TRAN_CLASS

    TRANCLASS resource information.

    OFM_OSC_TDQ

    TDQUEUE resource information.

    OFM_OSC_NETNAME

    NETNAME resource information.

  • System Tables

    Stores information about configurations and systems required for operating OSC servers.

    Table Name Description

    OFM_OSC_GETMAIN

    Address value of the GETMAIN area, which is shared between region processes.

    OFM_OSC_TRAN2SVC

    Service name which is used as transaction name.

    OFM_OSC_SVRINFO

    Status information of region processes.

    OFM_OSC_UPDATE_FILE

    UPDATE requests from the FILE resource.

    OFM_OSC_UPDATE_TDQ

    UPDATE requests from the TDQ resource.

    OFM_OSC_OPEN_FILE

    OPEN requests from the FILE resource.

    OFM_OSC_OPEN_TDQ

    OPEN requests from the TDQ resource.

    OFM_OSC_CONFIG

    Certain configuration settings of OSC.

    OFM_OSC_SACEE

    SACEE value which is TERMINAL ID.

    OFM_OSC_KEY2TRAN

    Transaction name which is used as a shortcut key.

    OFM_OSC_CSPG

    CSPG command.

    OFM_OSC_TSQINFO

    TSQ status information.

    OFM_OSC_TSQDATA

    TSQ data.

  • Service Log Tables

    Stores statistics information of transactions. For more information about service logs, refer to Managing the OSC System.

    Table Name Description

    OFM_OSC_OLOG

    Transaction statistics.

  • System Time Tables

    Stores time information of OSC systems.

    Table Name Description

    OFM_OSC_TX_TIME

    Hour and date information of OSC systems.

  1. For more information about how to use the oscinit tool, refer to OpenFrame Tool Reference Guide.

  2. For more information about each resource definition, refer to OpenFrame OSC Resource Definition Guide.

4. Creating Application Server Data Sets

Data sets that are defined in the OSC application server must be created before booting the server. If data sets are not created before startup, an error occurs.

You can create data sets either by executing a Batch JOB or by using the IDCAMS utility. If the OpenFrame/Batch is not installed, you may create data sets by using the idcams tool.

This section focuses on examples that use the IDCAMS utility script as well as the idcams tool.

  1. For more information about the IDCAMS utility, refer to OpenFrame Utility Reference Guide.

  2. For more information about the idcams tool, refer to OpenFrame Tool Reference Guide.

  3. For more information about performing batch jobs to create a data set, refer to OpenFrame TJES Administrator’s Guide.

4.1. Creating TDQ Intra-partition Data Sets

You must configure TDQ Intra-partition data sets according to the following rules.

  • Must be in the TSAM KSDS format.

  • Key field must be exactly 8 bytes long.

  • Size or format of records must be defined by the user, in accordance with the data length applied when using the actual TDQ Intra-partition queue.

The following IDCAMS script creates a TDQ intra-partition data set on volume 100000 named OSC.TDQLIB.INTRA.OSC00001. The first line deletes any existing data sets with that name.

DELETE OSC.TDQLIB.INTRA.OSC00001 CLUSTER
DEFINE CLUSTER (NAME(OSC.TDQLIB.INTRA.OSC00001) -
       KILOBYTES (128,128) -
       VOLUMES (100000) -
       INDEXED KEYS (8,0) -
       RECORDSIZE (128,32760) )

The following example creates a TSAM data set by passing the previous script (stored as a Unix file) to the IDCAMS utility.

$ IDCAMS < IDCAMS_OSC.TDQLIB.INTRA.sample

The following example executes the previous IDCAMS utility example by using the idcams tool.

$ idcams delete -t CL OSC.TDQLIB.INTRA.OSC00001
$ idcams define -t CL -n OSC.TDQLIB.INTRA.OSC00001 -o KS -k 8,0 -b 32768
  -l 128,32760 -s 1024,128,128 -v 100000

4.2. Creating TSQ Data Sets

TSQ data sets are made up of a data set for storing queue information and a data set for storing queue data.

TSQ Data Sets for Storing Queue Information

You must create TSQ data sets for storing queue information according to the following rules.

  • Must be in the TSAM KSDS format.

  • Key field must be exactly 16 bytes long.

  • Records must have a fixed length which is longer than 64 bytes. (variable length not allowed)

The following IDCAMS script creates a data set named OSC.TSQLIB.INFO.OSC00001 to store queue information. The first line deletes any existing data sets with that name.

DELETE OSC.TSQLIB.INFO.OSC00001 CLUSTER
DEFINE CLUSTER (NAME(OSC.TSQLIB.INFO.OSC00001) -
       KILOBYTES (128,128) -
       VOLUMES (100000) -
       INDEXED KEYS (16,0) -
       RECORDSIZE (64,64) )

The following example creates a TSAM data set by passing the previous script (stored as a Unix file) to the IDCAMS utility.

$ IDCAMS < IDCAMS_OSC.TSQLIB.INFO.sample
TSQ Data Sets for Storing Queue Data

You must create TSQ data sets for storing queue data according to the following rules.

  • Must be in the TSAM KSDS format.

  • Key field must be exactly 18 bytes long.

  • Size or format of records can be defined by the user in accordance with the data length applied when using TSQ.

The following IDCAMS script creates a data set named OSC.TSQLIB.DATA.OSC00001 to store queue data. The first line deletes any existing data sets with that name.

DELETE OSC.TSQLIB.DATA.OSC00001 CLUSTER
DEFINE CLUSTER (NAME(OSC.TSQLIB.DATA.OSC00001) -
       KILOBYTES (128,128) -
       VOLUMES (100000) -
       INDEXED KEYS (18,0) -
       RECORDSIZE (128,32760) )

The following example creates a TSAM data set by passing the previous script (stored as a Unix file) to the IDCAMS utility.

$ IDCAMS < IDCAMS_OSC.TSQLIB.DATA.sample

The following example executes the previous two IDCAMS utility examples by using the idcams tool. First, create a data set to save the queue information and then create a data set to save queue data.

$ idcams delete -t CL OSC.TSQLIB.INFO.OSC00001
$ idcams define -t CL -n OSC.TSQLIB.INFO.OSC00001 -o KS -k 16,0 -b 32768
         -l 64,64 -s 1024,128,128 -v 100000

$ idcams delete -t CL OSC.TSQLIB.DATA.OSC00001
$ idcams define -t CL -n OSC.TSQLIB.DATA.OSC00001 -o KS -k 18,0 -b 32768
         -l 128,32760 -s 1024,128,128 -v 100000

4.3. Creating FILE Data Sets

Unlike TDQ or TSQ data sets, FILE data sets are optional and only need to be created if the user uses FILE resources. In order for a user to use FILE resources, the data set defined in the DSNAME environment variable in the FILE resource definition must be created prior to starting up the system. If this data set is not created prior to system startup, an error occurs.

The following is an example of a FILE resource definition.

DEFINE FILE(OSCFILE)
       GROUP(TEST)
       DSNAME(OSC.FILE)
       RECORDFORMAT(V)
       ADD(YES)
       BROWSE(YES)
       DELETE(YES)
       READ(YES)
       UPDATE(YES)

To create a data set for a defined OSCFILE, an IDCAMS input script must be written to define a data set with a name that matches the DSNAME of the FILE resource (in this case, OSC.FILE). The following script creates a data set named OSC.FILE. This data set accepts variable length records that can be up to 1024 bytes long and has a key field that spans 64 bytes from the start of the record.

DEFINE CLUSTER (NAME(OSC.FILE) -
       KILOBYTES (128,128) -
       VOLUMES (100000) -
       INDEXED KEYS (64,0) -
       RECORDSIZE (64,1024) ))

The following example creates a TSAM data set by passing the previous script (stored as a UNIX file) to the IDCAMS utility.

$ IDCAMS < IDCAMS_OSC.FILE.sample

The following example executes the previous IDCAMS utility example by using the idcams tool.

$ idcams define -t CL -n OSC.FILE -o KS -k 64,0 -b 32768
  -l 64,1024 -s 1024,128,128 -v 100000

For more information about FILE resources, refer to OpenFrame OSC Resource Definition Guide.

5. Registering Application Server Resources

OSC provides a basic macro file with resource definitions that allows application servers to use basic OSC system functions. OSC also provides sample macro files that contain resource definitions corresponding to supported functions. The administrator must register the basic macro file to the application servers and, depending on what functions will be used by the servers, modify some of the sample macros and register them to the servers.

5.1. Registering Basic Resources

The basic macro file contains definitions for programs and transactions. These definitions are needed by the application servers to run properly. The basic macro file (osc.dat) is located in the ${OPENFRAME_HOME}/osc/resource directory and provided along with OSC installation.

To register the resources defined in the basic macro file, use the oscsdgen tool and register them into the OSC SD table. You can register the resources either by using oscsdgen or by specifying the OSC region.

The following script uses the oscsdgen tool to register the basic macro file (osc.dat) provided by OSC into the region OSC00001.

$ oscsdgen -c -r OSC00001 osc.dat

5.2. Registering User Resources

The sample macro file contains a number of definitions for OSC resources. The sample macro file is located in the ${OPENFRAME_HOME}/osc/resource directory, and it is automatically created when OSC is installed. The resource types covered include CONNECTION, FILE, JOURNALMODEL, PROGRAM, TDQ, TERMINAL, TRANCLASS, TRANSACTION, TSMODEL, and TYPETERM.

To register the sample macro files in the OSC SD table, use oscsdgen. These resource definitions can later be modified, deleted, and added through the [OSC] > [System Definition] menu in OpenFrame Manager.

  1. For more information about the [OSC] > [System Definition] menu in OpenFrame Manager, refer to OpenFrame Manager User Guide.

  2. For more information about the resources provided by the OSC system, refer to OpenFrame OSC Resource Definition Guide.

6. Setting Tmax Configuration File

Application servers, auxiliary servers and services that are used by those servers must be registered in the Tmax configuration file before they can be used.

6.1. Registering Application Servers and Services

There are two types of OSC application servers: interactive types and non-interactive types. To add one application server, both server types must be registered together. Application servers can be registered under the [SERVER] section of the Tmax configuration file.

The following is server registration information. Options other than a server name are the same as the Tmax server registration method.

Server Server Name

Non-interactive application servers

  • Tranclass server: Region name_Tranclass name (Example: OSC00001_TCL0)

  • PLT server: Region name (Example: OSC00001)

Interactive application servers

  • Interactive server: Region name (Example: OSC00001C)

The following shows service registration information. Register a service name by adding a suffix to it. For a Tranclass server, register the service with the same name as the server name.

Service Suffix Server

General transaction service

None

Tranclass server

PLT function service

P

PLT server

Interactive transaction service

C

Interactive server

DPL and function shipping service

M

Interactive server

Make sure the service name is only added to the end of a non-interactive application server name, not an interactive server name.

To provide efficient transaction processing, the administrator must modify application server settings depending on the role of each service on the server.

The following example registers a non-interactive application server (OSC00001_TCL0, OSC00001_TCL1, OSC00001) and an interactive application server(OSC00001C) of the OSC00001 Region, and then defines the services for each server:

*SERVER
OSC00001_TCL0   SVGNAME = svgbiz,
                TARGET = OSC00001,
                MIN = 1,
                MAX = 1,
                SCHEDULE = FA,
                CLOPT = "-o $(SVR).out -e $(SVR).err"

OSC00001_TCL1   SVGNAME = svgbiz,
                TARGET = OSC00001,
                MIN = 1,
                MAX = 1,
                SCHEDULE = FA,
                CLOPT = "-o $(SVR).out -e $(SVR).err"

OSC00001        SVGNAME = svgbiz,
                MIN = 1,
                MAX = 1,
                SCHEDULE = FA,
                CLOPT = "-o $(SVR).out -e $(SVR).err -n"

OSC00001C       SVGNAME = svgbiz,
                TARGET = OSC00001,
                CONV = O,
                MAX = 1,
                SCHEDULE = FA,
                CLOPT = "-o $(SVR).out -e $(SVR).err"
*SERVICE
OSC00001_TCL0         SVRNAME = OSC00001_TCL0
OSC00001_TCL1         SVRNAME = OSC00001_TCL1
OSC00001P             SVRNAME = OSC00001
OSC00001              SVRNAME = OSC00001
OSC00001M             SVRNAME = OSC00001C
OSC00001C             SVRNAME = OSC00001C

6.2. Registering Auxiliary Servers and Services

Auxiliary servers provide additional functions to application servers.

Several types of auxiliary servers are available. The OSC TDQ Log server manages TDQ logging functions, and the servers required to use the [OSC] menu in OpenFrame Manager manage OMC functions.

The following describes the server naming rule.

Server Server Name

OSC TDQ Log Server

Region name followed by "TL" (Example: OSC0001TL)

OpenFrame Manager/OSC Server

Region name followed by "OMC" (Example: OSC00001OMC)

The following example registers auxiliary servers.

*SERVER
OSC0001TL       SVGNAME = svgbiz,
                TARGET = osctlsvr,
                MAX = 1, SVRTYPE = UCS,
                CLOPT = "-o $(SVR).out -e $(SVR).err"

OSC00001OMC     SVGNAME = svgbiz,
                TARGET = oscossvr,
                MIN = 1,
                MAX = 5,
                SCHEDULE = RR,
                CLOPT = "-o $(SVR).out -e $(SVR).err -x OSCOSSVRSVC1:OSC00001_OMC1,
OSCOSSVRSVC2:OSC00001_OMC2,OSCOSSVRMON:OSC00001_MON,OSCOSSVR_ST:OSC00001_ST"

The names of the executable binaries for each server must be specified in the TARGET field of the server registration information.

Server Service Registration

OSC TDQ Log Server

Register the service with "_TL" added to the region name.

OpenFrame Manager/OSC Server

Add "_OMC1", "_OMC2", "_MON", "_ST" to the end of an application server name. Since a representative service processes all requests on an OMC server, the representative service must be specified in the CLOPT field of the registration information for a server.

In a multi-node environment, the service "_OMC1" is used to request a service to a specific node and the service "_OMC2" is used to request a service to any node. The service "_OMC1" has services to be requested to a specific node. To request the services depending on the FB_NODENAME field, add the ROUTING clause in a multi-node environment.

The following example registers services for auxiliary servers.

*SERVICE
OSC00001_TL          SVRNAME = OSC00001TL
OSC00001_OMC1        SVRNAME = OSC00001OMC
OSC00001_OMC2        SVRNAME = OSC00001OMC
OSC00001_MON         SVRNAME = OSC00001OMC
OSC00001_ST          SVRNAME = OSC00001OMC