Version 5.3.1
 —  Installation on Mainframes  —

Installing the Business Services Repository and Server Components

This section describes how to install the repository and server components for Natural Business Services. The following topics are covered:


Install Natural Business Services

This section describes how to install Natural Business Services. The following topics are covered:

Dataset Summary

The following table identifies the Natural Business Services dataset, job, and step names:

Dataset Name Job Name Step Name
NBSnnn.INPL I061 1370
NBSnnn.IUPD I061 1372
NBSnnn.SYS1 I050 1372
NBSnnn.SYS2 I050 1373
NBSnnn.NCSR I061 1371

Note:
The NBSnnn.NCSR dataset is automatically installed on the server during the installation of Natural Business Services. You must manually install this dataset on any client that does not have Natural Business Services installed. For information, see Installing the Natural Client Service Runtime Component.

Step 1: Install Natural Construct

You must install the new version of Natural Construct before installing Natural Business Services. For information, see Installing Natural Construct.

Step 2: Create Administration Subsystem Data Files (First-Time Installation Only)

If you are installing Natural Business Services for the first time, you must create the Business Service Administration subsystem data files. To do this, load two files from the installation tape: one contains security-related data (secured data) and the other contains all other data (unsecured data).

Because the data is contained in two files, you can cipher secured data without ciphering all Business Service Administration subsystem data. When loaded, the files are empty. After the physical files are created, a Natural program populates the files. To dynamically access these files, use the following LFILE values:

This section describes how to load secured and unsecured data. The following topics are covered:

Load Secured Data

Loading this data differs, depending on whether you cipher the secured data. The following sections describe how to load secured data ciphered and unciphered.

Note:
Minimum recommended sizes are: DSSIZE=50B, NISIZE=50B, and UISIZE=20B.

Ciphered

To cipher secured data, refer to the sample job in the NBSnnn.JOBS (z/OS) or NBSnnn.LIBJ (z/VSE) dataset. You may have to modify the job to reflect your environment. To load this file, use the same file number and DBID values used for logical file 135.

Note:
SMA (System Maintenance Aid) does not support the loading of secured and ciphered data under BS2000/OSD.

Unciphered

The Adabas ADALOD utility loads the Business Service Administration subsystem data file. The NBSnnn.SYS1 dataset is an unloaded Adabas V7 file; use this file as input to the ADALOD utility. To load this file, use the same file number and DBID values used to define NTLFILE 135 (see Step 2: Load Administration Subsystem Components).

Set the following minimum sizes for the ADALOD utility:

Load Unsecured Data

The Adabas ADALOD utility loads the Business Service Administration subsystem data file. The NBSnnn.SYS2 dataset is an unloaded Adabas V7 file; use this file as input to the ADALOD utility. To load this file, use the same file number and DBID values used to define NTLFILE 136 (see Step 2: Load Administration Subsystem Components).

Set the following minimum sizes for the ADALOD utility:

Step 3: Load Administration Subsystem Components

This dataset contains modules for the Business Service Administration subsystem. The modules are stored in the SYSBIZ, SYSLIBS, and SYSTEM libraries in the FNAT system file. Ensure that the FNAT parameter value correctly identifies the desired system file. Use the following input to the INPL utility:

INPL
B
FIN

Note:
Assign NBSnnn.INPL to CMWKF01.

Step 4: Load Dataset Containing Updates and Fixes

This INPL dataset contains updates and fixes to Natural Business Services. Load this dataset after loading the NBSnnn.INPL dataset.

Step 5: Migrate Repository Data (Conditional)

You have three options to migrate repository data from an existing version of Natural Business Services to a new version. If you created a new repository file and have a new FUSER file for your new environment, use one of the options below.

Note:
If you created a new repository file, but want to use your existing FUSER file, use option 1.

Option 1: Deploy Services

Start of instruction setTo deploy your business services to the new repository:

Note:
If you are moving the Natural objects, the SYSMAIN utility must be available in the new environment. If not, you must move the objects manually. In addition, you must manually copy any Natural objects you have coded yourself. Natural Business Services only recognizes modules that are referenced in the code generation specifications.

Option 2: Copy Natural Objects

Start of instruction setTo copy the Natural objects:

  1. Re-create your domain and steplib definitions in the new repository file.

  2. Copy your business service Natural objects to your new Natural Business Services environment (including the subprogram proxies).

    Note:
    The Natural SYSMAIN utility must be available in the new environment. If not, you must move the objects manually.

  3. Use the Natural Construct batch generator to regenerate the service proxies in the appropriate libraries.

    This will populate the service repository file.

Option 3 – Import/Export Service, Domain, and Steplib Definitions

Start of instruction setTo import/export service, domain, and steplib definitions:

  1. Enter the "MENU AA MM DT" direct command from the SYSBIZ library in Natural Business Services V5.2.

    The Transfer Domains menu is displayed.

  2. Enter "XD" in Function to export your service, domain, and steplib definitions to a work file.

    The Export Domains window is displayed.

  3. Enter "ID" in Function to import your service, domain, and steplib definitions to your new environment.

    The Import Domains window is displayed.

For more information, see Data Transfer Utilities.

Step 6: Migrate Security Group and User Definitions (Conditional)

Start of instruction setTo import/export security group and user definitions:

  1. Enter the "MENU SA MM DT" direct command from the SYSBIZ library in Natural Business Services V5.2.

    The Transfer Groups menu is displayed.

  2. Enter "XG" in Function on the Transfer Groups menu to export your security group and user definitions to a work file.

    The Export Groups window is displayed.

  3. Enter "IG" in Function on the Transfer Groups menu to import your security group and user definitions to your new environment.

    The Import Groups window is displayed.

For more information, see Data Transfer Utilities.

Top of page

Activate the Business Service Administration Subsystem

To use the Business Service Administration subsystem, you must first activate the system. This section describes a series of updates and system-related functions you must perform to use the supplied demo application and samples. The following topics are covered:

Step 1: Verify System File Assignments

This step ensures that the profile was created correctly.

Start of instruction setTo verify the system file assignments:

  1. Invoke Natural using the new SYSBIZ profile.

  2. Log onto the SYSBIZ library.

  3. Issue the VERIFY command.

  4. Enter "LF".

    The following output is displayed:

    Construct System File (LFILE 227) checked successfully
    NBS Secured File (LFILE 136) checked successfully
    NBS Unsecured File (LFILE 135) checked successfully
    FNAT System File checked successfully
    FUSER System File checked successfully
    FDIC System File checked successfully

    Note:
    If you are installing Natural Business Services without Natural Construct, you do not require Predict. Therefore, you may encounter an Adabas 3061 error while reading the FDIC system file. If this happens, use the SYSPROF command to verify the system file assignments and, if necessary, override the assignments using the LFILE parameter or relink Natural with a suitable NTLFILE macro.

If any file fails to verify:

  1. Correct the SYSBIZ profile.

  2. Restart your Natural session.

  3. Reissue the VERIFY command.

Step 2: Verify Natural Subtask Support

If your operating system supports multiple Natural batch sessions in one address space (for example, z/OS), use the Multi-Tasking Verification utility to verify that your environment is configured correctly. Then test the servers to ensure they are operating correctly.

Multi-Tasking Verification Utility

The TESTTASK utility verifies that your batch Natural nucleus and ADALNK are reentrant. To run servers in an environment that supports multiple Natural batch sessions in one address space, both conditions are required.

Before using the TESTTASK utility, ensure the following:

The Natural batch nucleus and ADALNK reentrant are provided with the following SMA jobs:

To start multiple Natural tasks, define the TESTSTSK module as a subtask started by TESTTASK. If your batch nucleus or ADALNK is not reentrant, the job that runs TESTTASK will not end. Otherwise, tracing is written to the job output showing the execution status of the subtasks.

The following JCL excerpt shows the parameters required to call TESTTASK:

SYSBIZ,userid,pswd
GLOBALS IM=D ID=/ IA=:
TESTTASK
*/ETID=12301,STACK=(LOGON SYSBIZ,userid,pswd;TESTSTSK 10)
*/ETID=12302,STACK=(LOGON SYSBIZ,userid,pswd;TESTSTSK 10)
*/ETID=12303,STACK=(LOGON SYSBIZ,userid,pswd;TESTSTSK 10)
*/ETID=12304,STACK=(LOGON SYSBIZ,userid,pswd;TESTSTSK 10)
*/ETID=12305,STACK=(LOGON SYSBIZ,userid,pswd;TESTSTSK 10)
.
FIN
/*

The job must also define work file 1. This work file can be routed to a printer device.

Step 3: Verify USR* Subprogram Installation

This step verifies that all required USR modules are available from within the current steplib chain.

Start of instruction setTo verify that all required USR modules are available:

  1. Log onto the SYSBIZ library.

  2. Issue the VERIFY command.

  3. Enter "US".

    The VERIFY program calls the USR routines to confirm their availability.

Step 4: Verify Software AG Editor Installation

This step verifies the installation of the Software AG editor.

Start of instruction setTo verify the installation of the Software AG editor:

  1. Log onto the SYSBIZ library.

  2. Invoke the VERIFY program.

  3. Enter "SE".

    The VERIFY program:

    1. Opens a Software AG editor session.

    2. Writes lines to the Software AG editor.

    3. Reads the lines back from the Software AG editor.

    4. Closes the Software AG editor session.

    5. Writes out a success/fail message.

Step 5: Load Default Repository Data

Regardless of whether you are installing for the first time or over an existing version, you must perform this step to populate the Natural Business Services files with data required by version 5.3. The CSRLOAD program clears the source area, loads the current repository data, and generates entries required for the Broker attribute file. You must copy the entries manually.

Start of instruction setTo load the repository data:

  1. Log onto the SYSBIZ library.

  2. Invoke the CSRLOAD program.

    The following panel is displayed:

    This process will load the current Business Files. Make sure your LFILES      
    are set correctly. This program also clears the source area and generates     
    entries required for the BROKER Attribute File. These must be copied manually.
                                                                                  
    Enter default values to be used to establish server records...                
      Broker ID ........ BKRnnn__________________________                         
      Server qualifiers Prefix: __________ Suffix: __________                     
      Server Class ..... BUSINESS________________________ Unicode (Y/N): N        
      JCL Text Member .. BATCHTXT                                                 
      Transaction ...... NATBAT__                                                 
      Subtask Support .. Y                                                        
      Profile FNAT DBID  _13000                                                   
      Profile FNAT FNR . __1300                                                   
      Profile .......... SYSBIZ__                                                 
                                                                                  
    Natural Security Settings...                                                  
      Servers under NSC  _                                                        
      User id .......... ________________________________                         
      Password .........                                                          
                                                                                  
    Mark default records to be loaded...                                          
      X Users             X Groups            X Domains            X Steplibs     
      X Servers           X Business Services X Security Links                    
    

    Tip:
    If you make any errors specifying this data, you can manually change the repository data in the Business Service Administration subsystem (enter "MENU SA MM SE" on the command line).

  3. Specify default settings for the records to be generated.

    You can use the default values for most settings. Specify the following fields:

    Field Description
    Broker ID Name of the broker to use in this environment.
    Server qualifiers Prefix and suffix values added to the names of the server records being created. The combination of prefix and suffix characters must be less than or equal to 10.
    Unicode If you want NBS servers to invoke Natural subprograms that contain Unicode parameters, enter “Y” in this field. For more information, see Use Unicode Parameters for Your Business Service.

    Notes:

    1. The Broker attribute file definition generated by CSRLOAD will be different for a Unicode dispatcher, since the generated entry for SERVER=DISPATCH, SERVICE=MAIN will require CONVERSION=SAGTCHA.
    2. The servers must run in a Unicode-enabled Natural environment.
    Transaction Name of the Natural nucleus under which the service will run. The default transaction name is NATBAT, but you can change the name if desired.
    Subtask support Verification of Natural subtask support. If the TESTTASK program completed successfully, “Y” is displayed. If not, “N” is displayed. For more information, see Step 2: Verify Natural Subtask Support.
    Profile FNAT DBID and FNR Database ID and file number for the Natural FNAT system file in which the SYSBIZ profile is located.
    Profile Name of the profile used. By default, SYSBIZ is displayed.
    Natural Security Settings If your servers run under Natural Security, mark Servers under NSC and specify a user ID and password; use the specified user ID and password to start all servers.
  4. Press Enter.

    The CSRLOAD program displays all records that are being loaded.

    Note:
    If any records currently exist in your Natural Business Services files, they will not be replaced. The output report indicates which records were not replaced. Rename or delete the existing records and rerun the CSRLOAD program, specifying only the objects you want to load.

Load Servers Only

When using the CSRLOAD program, you can optionally load the servers only (security, dispatch, security, etc.). When loading servers, determine whether the servers will use Natural Security and whether they will use batch jobs as Natural subtasks. Although the servers can use any combination of these options, problems may arise if you load a server that uses one option (for example, without assigning Natural Security) and then change the option (for example, specify Natural Security later). To eliminate this problem, you can load different sets of servers that have different options and specify a prefix or suffix to identify each set. For example, you can specify an "NSC-" prefix, select Servers under NSC, and enter a user ID and password. This allows the same set of servers to start up with and without Natural Security.

Note:
To allow the secure and non-secure servers to run at the same time, define the settings for both sets of servers in Broker.

Note:
The JCL templates must be different for both sets of servers, based on how the LOGON is issued. For more information, see Step 10: Define Batch Transaction.

You can also specify batch or subtask servers. Subtask servers are ideal as they use the least resources. The dispatch and security servers can run as Natural subtasks called from the Natural session that is running the attach server. The downside to this option is that it is more difficult to debug the servers. If the dispatch or security servers are not responding, run them as batch jobs first to determine the problem. To automatically load the batch job server definitions, change the Subtask Support option to "N" and change the prefix (for example, to BTCH-).

Tip:
Once the servers are running correctly, convert the security batch job into a started task. For information, see Step 5: Define and Start an Attach Server.

Start of instruction setTo load the servers only:

  1. Log onto the SYSBIZ library.

  2. Invoke the CSRLOAD program.

  3. Select one or more server options.

  4. De-select all options except Servers in the Default Records to be Loaded section.

    For example:

    This process will load the current Business Files. Make sure your LFILES      
    are set correctly. This program also clears the source area and generates     
    entries required for the BROKER Attribute File. These must be copied manually.
                                                                                  
    Enter default values to be used to establish server records...                
      Broker ID ........ BKRnnn__________________________                         
      Server qualifiers Prefix: __________ Suffix: __________                     
      Server Class ..... BUSINESS________________________ Unicode (Y/N): N        
      JCL Text Member .. BATCHTXT                                                 
      Transaction ...... NATBAT__                                                 
      Subtask Support .. Y                                                        
      Profile FNAT DBID  _13000                                                   
      Profile FNAT FNR . __1300                                                   
      Profile .......... SYSBIZ__                                                 
                                                                                  
    Natural Security Settings...                                                  
      Servers under NSC  _                                                        
      User id .......... ________________________________                         
      Password .........                                                          
                                                                                  
    Mark default records to be loaded...                                          
      _ Users             _ Groups            _ Domains            _ Steplibs     
      X Servers           _ Business Services _ Security Links 
                       
    
  5. Press Enter.

    The selected servers are loaded.

Create Servers for Other Environments

You can also run the CSRLOAD utility again to create servers for other environments. To create servers for other environments, add a prefix or suffix as server qualifiers (for example, "NSC-" or "-NSC" to identify secure servers) and specify an alternate server class.

Step 6: Update Broker Attribute File

When the CSRLOAD program ends, the Natural source area contains the definitions required for the Broker attribute file. Copy these definitions from the source area to your Broker attribute file and confirm the following global settings:

*-------------------------------------------------------------------*
* Broker specific Attributes / Definition of global resources       *
*-------------------------------------------------------------------*
 DEFAULTS = BROKER
   NUM-CLIENT        = 250
   NUM-CONVERSATION  = 1000
   NUM-SERVER        = 50
   NUM-SERVICE       = 500
   NUM-LONG-BUFFER   = 500
   NUM-SHORT-BUFFER  = 2000

Step 7: Verify Broker Attribute File

This step verifies the additions to the Broker attribute file.

Start of instruction setTo verify the Broker attribute file additions:

  1. Log onto the SYSBIZ library.

  2. Issue the VERIFY command.

  3. Enter "AF".

    A confirmation message is displayed:

    Business service                         Broker service
    ------------------------- -------------------------------------------------
    ATTACH                    BKR057/BUSINESSSERVICES-QA/ATTACH/MAIN
                              MAIN and CMD services registered successfully
    CFACTORY                  BKR057/BUSINESSSERVICES-QA/CFACTORY/MAIN
                              MAIN and CMD services registered successfully
    DISPATCH                  BKR057/BUSINESSSERVICES-QA/DISPATCH/MAIN
                              MAIN and CMD services registered successfully
    SECURITY                  BKR057/BUSINESSSERVICES-QA/Security/MAIN
                              MAIN and CMD services registered successfully
    TIMESTAMP                 BKR057/BUSINESSSERVICES-QA/TIMESTAMP/MAIN
                              MAIN and CMD services registered successfully

If any errors appear in the output, correct either the records in your Natural Business Services file or the definitions in your Broker attribute file and rerun the test.

Step 8: Verify Message Queue API

This step verifies the message queue API.

Start of instruction setTo verify the message queue API:

  1. Log onto the SYSBIZ library.

  2. Invoke the VERIFY program.

  3. Enter "MQ".

    The VERIFY program:

    1. Calls the message queue (conversation factory) APIs to pass data (as a multi-part message). This confirms that no limits are specified on Broker message lengths that will cause SQUSEND/SQURECV to fail.

    2. Sends the binary values from H'00' to H'FF'. This confirms that no translation routine was added to the Broker attribute file.

    3. Confirms that the data it receives matches the data it sent.

Step 9: Confirm all Verifications

This step confirms that all verifications have been successful.

Start of instruction setTo confirm all verifications:

  1. Log onto the SYSBIZ library.

  2. Invoke the VERIFY program.

  3. Enter "*".

    The program performs all verifications and confirms that:

Step 10: Define Batch Transaction

In this step, create a new JCL template (BATCHTXT) you can use to launch your servers. Sample templates are supplied in the SYSBIZ library. Edit the following member for your server environment:

To define the batch transaction:

10A: Specify a Job Name

The job name can either be a specific value or a combination of the &JOB-PREFIX&JOB-NR substitution parameters (derives a unique job name). When the JCL is generated, the &JOB-PREFIX value is assigned a two-character value associated with the server it is invoking.

10B: Define Logon Parameters

If your servers run under Natural Security, supply a user ID and password as part of the LOGON SYSBIZ command. You cannot use the job name to define the user ID because the value is normally generated dynamically. Include AUTO=OFF in your NATPARM.

Under Natural Security, the LOGON command should appear as follows:

SYSBIZ user-ID,password

where user ID is a valid user linked to the SYSBIZ library.

Note:
Under z/OS, you can also specify the USERID=YES parameter in the NATOS module and supply a USERID parameter on your job card. In that case, the USERID parameter on the job card defines the Natural Security user, not the job name.

Example of Natural Input Parameters

Following the LOGON, the Natural input statements should appear as follows:

SPSSTART
&BUSINESS-SERVICE,%
&USER-ID,%
&PASSWORD,%
&TRACE-OPTION,%
&TRACE-LOCATION,%
&Q-BROKER-ID,%
&Q-USER-ID,%
&Q-TOKEN,%
&Q-Security-TOKEN,%
&Q-CONV-ID
&PROGPARM
FIN

10C: Define Work File 7

The JCL member should define work file 7 (CMWKF07).

Save your modified JCL member as BATCHTXT.

10D: Test the Submitted Job

Start of instruction setTo test the submitted job:

  1. Invoke the BATCHTST program to test the generated JCL.

  2. Override any values to reflect your environment.

  3. Press Enter to generate the JCL into the source area.

  4. Review the JCL for validity.

The Natural input statements should now contain the following:

VERIFY
*
.
SPSWKF07

If necessary, modify the original BATCHTXT member and repeat the test. Once valid JCL is generated, rerun BATCHTST and mark the Submit option. This submits a job to run the verify steps in batch. Monitor and review the submitted job using normal operating system commands.

Step 11: Launch the Attach Server

Launch the attach server. This server allows you to issue commands to the server.

Start of instruction setTo launch the attach server:

  1. Log onto the SYSBIZ library.

  2. Enter "MENU SA MS" on the command line.

    The Manage Servers panel is displayed:

     SPCMS      ***** Business Service Administration Subsystem *****        SPCMS0 
     Feb 14,06                    - Manage Servers -                        8:58 PM 
                                                                                    
     Action Server                           Type    Attach Manager                 
     ------ -------------------------------- ------- ------------------------------ 
      ___   ATTACH-53-EXX                    Attach                                 
      ___   ATTACH-53-EXX-SECURE             Attach                                 
      ___   DISPATCH-53-EXX                  Server                                 
      ___   DISPATCH-53-EXX-BATCH            Server  ATTACH-53-EXX                  
      ___   DISPATCH-53-EXX-SECURE           Server  ATTACH-53-EXX-SECURE           
      ___   DISPATCH-53-EXXTEST              Server                                 
      ___   SECURITY-53-EXX                  Server                                 
      ___   SECURITY-53-EXX-BATCH            Server  ATTACH-53-EXX                  
      ___   SECURITY-53-EXX-SECURE           Server  ATTACH-53-EXX-SECURE           
     Server .....: ________________________________ Server type ..: _               
     Replica ID .: ________________________________ Repeat command: _               
     Last command:                                                                  
     Respondent .:                                                                  
                                                                                    
                                                                                    
     Direct Command: ____________________________________________________________   
     Debug      EndJob     EndService EnVironmnt Initiate   Ping       Refresh      
     SHutdown   STeplibs   SYsprof    (PF4=CLog) (PF5=flip)                         
    
  3. Type "I" beside the attach server.

  4. Press Enter to initiate the attach server.

Note the name of the batch job submitted. In a few seconds, you should be able to issue other commands, such as Ping (P) or Environment (EV). If the “ETB Error 7/7 (Service not registered)” message is displayed, review the job, resolve any errors in BATCHTXT, and repeat the process.

Step 12: Launch Remaining Servers

With an attach server running, use the INITIATE command to launch the Timestamp service. In a few seconds, you should be able to ping this service. If not, perform one of the following steps:

Review this report and try to diagnose the startup problem. Modify the Timestamp service records (enter "MENU SA MM SE" on the command line), as well as the records for all other services that use the SUBTASKB server start routine. Repeat the procedure until you are able to initiate and ping all servers.

For more information, see Natural Business Services Administration.

Top of page