This section describes how to install the repository and server components for Natural Business Services. The following topics are covered:
This section describes how to install Natural Business Services. The following topics are covered:
Step 2: Create Administration Subsystem Data Files (First-Time Installation Only)
Step 6: Migrate Security Group and User Definitions (Conditional)
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.
You must install the new version of Natural Construct before installing Natural Business Services. For information, see Installing Natural Construct.
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:
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.
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) 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.
Job I050, Step 1372; NBSnnn.SYS1 dataset
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:
MAXISN=20000
DSSIZE=5
NISIZE=300B
UISIZE=50B
Job I050, Step 1373; NBSnnn.SYS2 dataset
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:
DSSIZE=200B
NISIZE=100B
UISIZE=40B
Job I061, Step 1370; NBSnnn.INPL dataset
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.
Job I061, Step 1372; NBSnnn.IUPD dataset
This INPL dataset contains updates and fixes to Natural Business Services. Load this dataset after loading the NBSnnn.INPL dataset.
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.
To deploy your business services to the new repository:
Use the Deploy option for a Natural Business Services plug-in in your existing environment.
For information, see the applicable plug-in guide.
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.
To copy the Natural objects:
Re-create your domain and steplib definitions in the new repository file.
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.
Use the Natural Construct batch generator to regenerate the service proxies in the appropriate libraries.
This will populate the service repository file.
To import/export service, domain, and steplib definitions:
Enter the "MENU AA MM DT" direct command from the SYSBIZ library in Natural Business Services V5.2.
The Transfer Domains menu is displayed.
Enter "XD" in Function to export your service, domain, and steplib definitions to a work file.
The Export Domains window is displayed.
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.
To import/export security group and user definitions:
Enter the "MENU SA MM DT" direct command from the SYSBIZ library in Natural Business Services V5.2.
The Transfer Groups menu is displayed.
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.
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.
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:
This step ensures that the profile was created correctly.
To verify the system file assignments:
Invoke Natural using the new SYSBIZ profile.
Log onto the SYSBIZ library.
Issue the VERIFY command.
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:
Correct the SYSBIZ profile.
Restart your Natural session.
Reissue the VERIFY command.
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.
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 Step 2: Load Administration Subsystem Components.
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.
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:
Log onto the SYSBIZ library.
Issue the VERIFY command.
Enter "US".
The VERIFY program calls the USR routines to confirm their availability.
This step verifies the installation of the Software AG editor.
To verify the installation of the Software AG editor:
Log onto the SYSBIZ library.
Invoke the VERIFY program.
Enter "SE".
The VERIFY program:
Opens a Software AG editor session.
Writes lines to the Software AG editor.
Reads the lines back from the Software AG editor.
Closes the Software AG editor session.
Writes out a success/fail message.
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.
To load the repository data:
Log onto the SYSBIZ library.
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).
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:
|
| 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. |
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.
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.
To load the servers only:
Log onto the SYSBIZ library.
Invoke the CSRLOAD program.
Select one or more server options.
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
|
Press Enter.
The selected servers are loaded.
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.
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
This step verifies the additions to the Broker attribute file.
To verify the Broker attribute file additions:
Log onto the SYSBIZ library.
Issue the VERIFY command.
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.
This step verifies the message queue API.
To verify the message queue API:
Log onto the SYSBIZ library.
Invoke the VERIFY program.
Enter "MQ".
The VERIFY program:
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.
Sends the binary values from H'00' to H'FF'. This confirms that no translation routine was added to the Broker attribute file.
Confirms that the data it receives matches the data it sent.
This step confirms that all verifications have been successful.
To confirm all verifications:
Log onto the SYSBIZ library.
Invoke the VERIFY program.
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
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/OSD)
For other environments, create the BATCHTXT member starting with a valid Natural batch job applicable to your operating system.
To define the batch transaction:
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.
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.
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
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.
To test the submitted job:
Invoke the BATCHTST program to test the generated JCL.
Override any values to reflect your environment.
Press Enter to generate the JCL into the source area.
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.
Launch the attach server. This server allows you to issue commands to the server.
To launch the attach server:
Log onto the SYSBIZ library.
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)
|
Type "I" beside the attach server.
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.
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.