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

• Install Natural Business Services

• Activate the Business Service Administration Subsystem

---

Install Natural Business Services

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

• Data Set Summary

• Step 1: Install Natural Construct

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

• Step 3: Load Administration Subsystem Components

• Step 4: Migrate Repository Data (Conditional)

• Step 5: Migrate Security Group and User Definitions (Conditional)

Data Set Summary

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

Data Set Name	Job Name	Step Name
NBSnnn.INPL	I061	1370
NBSnnn.SYS1	I050	1372
NBSnnn.SYS2	I050	1373
NBSnnn.NCSR	I061	1371

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)

• Job I050, Step 1370

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:

• LFILE 135 to access the secured data

• LFILE 136 to access the unsecured data

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

• Load Secured Data
• Load Unsecured Data

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.

Ciphered

• Job I050, Step 1370 and 1371

To cipher secured data, refer to the sample job in the NBSnnn.JOBS (z/OS) or NBSnnn.LIBJ (z/VSE) data set. 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.

Unciphered

• Job I050, Step 1372; NBSnnn.SYS1 data set

The Adabas ADALOD utility loads the Business Service Administration subsystem data file. The NBSnnn.SYS1 data set 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 3: Load Administration Subsystem Components).

Set the following minimum sizes for the ADALOD utility:

• MAXISN=20000

• DSSIZE=5

• NISIZE=300B

• UISIZE=50B

Load Unsecured Data

• Job I050, Step 1373; NBSnnn.SYS2 data set

The Adabas ADALOD utility loads the Business Service Administration subsystem data file. The NBSnnn.SYS2 data set 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 3: Load Administration Subsystem Components).

Set the following minimum sizes for the ADALOD utility:

• DSSIZE=200B

• NISIZE=100B

• UISIZE=40B

Step 3: Load Administration Subsystem Components

• Job I061, Step 1370; NBSnnn.INPL data set

This data set 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

Step 4: Migrate Repository Data (Conditional)

You have two 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.

Option 1: Copy Natural Objects

To 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.

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

Option 2: Import/Export Service, Domain, and Steplib Definitions

To import/export service, domain, and steplib definitions

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

   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 5: Migrate Security Group and User Definitions (Conditional)

To import/export security group and user definitions

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

   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.

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

• Step 2: Verify Natural Subtask Support

• Step 3: Verify USR* Subprogram Installation

• Step 4: Verify Software AG Editor Installation

• Step 5: Load Default Repository Data

• Step 6: Update Broker Attribute File

• Step 7: Verify Broker Attribute File

• Step 8: Verify Message Queue API

• Step 9: Confirm all Verifications

• Step 10: Define Batch Transaction

• Step 11: Launch the Attach Server

• Step 12: Launch Remaining Servers

Step 1: Verify System File Assignments

This step ensures that the profile was created correctly.

To verify the system file assignments

1. Invoke Natural using the new SYSBIZ profile.

2. Log on to 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 includes the ADALNKR module or modified ADALNK module. For more information, see Make the Nucleus Reentrant.

• The ADALNKR or modified ADALNK module is updated to the correct SVC.

• The batch nucleus specifies ADAPRM=ON.

• The INCLUDE statement for ADAUSER is removed.

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

• Job I055, Steps 1370–1385

• Job I060, Steps 1370–1372

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.

To verify that all required USR modules are available

1. Log on to 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.

To verify the installation of the Software AG editor

1. Log on to 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 8.2. 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.

To load the repository data

1. Log on to 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. Notes: 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. 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.

Notes:

1. To allow the secure and non-secure servers to run at the same time, define the settings for both sets of servers in Broker.
2. 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-).

To load the servers only

1. Log on to 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.

To verify the Broker attribute file additions

1. Log on to 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.

To verify the message queue API

1. Log on to 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.

To confirm all verifications

1. Log on to the SYSBIZ library.

2. Invoke the VERIFY program.

3. Enter "*".

   The program performs all verifications and confirms that:

   • the required Adabas files are available

   • the required class/server/service combinations for NBS have been defined in the Broker attribute file

   • the required Natural user exit routines are available

   • the program editor is available

   • the middleware connection is working

   • the steplib chain settings are correct

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:

• BATCHJCL (z/OS)

• BATCHDCL (z/VSE)

• BATCHBCL (BS2000)

• For other environments, create the BATCHTXT member starting with a valid Natural batch job applicable to your operating system.

To define the batch transaction:

• 10A: Specify a Job Name
• 10B: Define Logon Parameters
• 10C: Define Work File 7
• 10D: Test the Submitted Job

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.

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).

• If you are using the Natural subtasking feature, define work file 7 as a temporary file.

• If you are invoking all servers as separate batch jobs, define work file 7 as a permanent file.

Save your modified JCL member as BATCHTXT.

10D: Test the Submitted Job

To 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.

To launch the attach server

1. Log on to 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 - Manage Servers - 8:58 PM Action Server Type Attach Manager ------ -------------------------------- ------- ------------------------------ ___ ATTACH-82-EXX Attach ___ ATTACH-82-EXX-SECURE Attach ___ DISPATCH-82-EXX Server ___ DISPATCH-82-EXX-BATCH Server ATTACH-82-EXX ___ DISPATCH-82-EXX-SECURE Server ATTACH-82-EXX-SECURE ___ DISPATCH-82-EXXTEST Server ___ SECURITY-82-EXX Server ___ SECURITY-82-EXX-BATCH Server ATTACH-82-EXX ___ SECURITY-82-EXX-SECURE Server ATTACH-82-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:

• If you are not using the Natural subtasking feature, review the JCL that was submitted and correct BATCHTXT.

• If you are using the Natural subtasking feature, enter "D" (Debug command) beside the Timestamp server. A report is displayed, indicating the outcome. For example:

  ===================================ATTACH=============================
  BKR057/BUSINESSSERVICE-QA/ATTACH/MAIN/B0FC1B6797BFAD01B0FC2313E9356601
  Response: 1              Response code: 0000          Message ID:
  Natural startup parameters ...
  FNAT=(1000,1000),PROFILE=SYSBIZ, STACK=(LOGON SYSBIZ;SPSSTART USING_CMPARM
  ;SPSDATA) ETID=E1834186
  Response: 2              Response code: 0000          Message ID:
  Data passed via CMUPARM ...
  Service=TIMESTAMP,Init User=,Parent Rid=B0FC1B6797BFAD01B0FC2313E9356601
  Response: 3              Response code: 0000          Message ID:
  Natural startup results ...
  SPSSTART started in debug mode, for service TIMESTAMP
  Checking system files ...
  System files validated
  Logon performed
  Register performed
  Server program: SPSTIMS    *DATA:   -1
  Program SPSDATA invoked.    *DATA =    0
  Stopping test due to debug mode

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.