These notes describe the release of Natural Business Services (NBS) V5.3. The following topics are covered:
The following table lists cross-references to information about the software and hardware prerequisites for Natural Business Services:
| Operating Platform | Cross-Reference |
|---|---|
| Mainframe | For information on software prerequisites, see Prerequisites. For information on hardware prerequisites, see Operating Environments. |
| Unix | For information on software and hardware prerequisites, see Product Requirements. |
| Windows | For information on software and hardware prerequisites, see Introduction. |
This section contains important information you should read before installing this version of Natural Business Services. The following topics are covered:
The installation of Natural Construct has been simplified by combining the INPL and error message datasets into one. Since Natural Construct is a prerequisite for Natural Business Services, all error messages for Natural Business Services will now be installed with Natural Construct.
With the next version of SUSE Linux Enterprise Server (beyond SLES 11) and Red Hat Enterprise Linux (beyond RHEL 5), our products will no longer support the 32-bit OS versions. Therefore, migration to the corresponding 64-bit OS version is recommended.
If you are using the Natural Construct Browse* models on Unix, Natural version 6.3.4 PL2 or higher is required for the generated code to work correctly.
This section describes the new features and enhancements in this version of Natural Business Services and Natural Construct. The following topics are covered:
This section describes the new features and enhancements in Natural Business Services V5.3. The following topics are covered:
The setup.exe file will now copy NBS configuration and customizable files to the following folder:
%ALLUSERPROFILE%/Application Data/Software AG/Natural Business Services/
In addition, if the installation script detects versions installed before 5.3.1.0, it will prompt the user to copy *.config and *.xml files to this folder.
When running the CSRLOAD program on Unix, you can now specify the path to the batch output file for each server session. For information, see Step 10: Load Default Repository Data.
The Business Service wizard now contains intelligence to “recognize” methods associated with Natural Construct models. When creating a business service using the Based on existing subprogram(s) option, you can have the wizard use the standard methods associated with the Object-Browse, Object-Maint, or Object-Browse-Select models (such as BROWSE, FindBy, UPDATE, NEXT, etc.). For information, see Select the Type of Methods Generated.
When using the Business Service wizard to generate new subprograms for data access (i.e., the By generating new subprograms for data access option on the Define the Service panel in the Eclipse plug-in or the Choose Type panel in the Natural plug-in), one of the options is to generate a single view data access service. This option allows the service to browse by a non-unique key while uniquely maintaining the data object using Adabas’s internal sequence number (*ISN).
To take advantage of this feature, the business service must be generated:
With both the browse and maintenance functions
For a single view
With the GET-BY-ISN option enabled
To enable the GET-BY-ISN option:
Logon to the SYSCSTX library.
Edit the CSXDEFLT subprogram and uncomment the following code:
VALUE 'GET-BY-ISN'
CSADEFLT.PARM-VALUE := TRUE
Stow CSXDEFLT.
Use the SYSMAIN utility to copy CSXDEFLT to SYSLIBS.
Note:
To implement this functionality for an existing business service,
regenerate the business service after specifying the GET-BY-ISN option. (Do not
regenerate the proxy.)
To test that this feature is working:
Open the context menu for the business service in the NBS Repositories view.
For information, see:
Eclipse plug-in: Test a Business Service
Natural plug-in: Test a Business Service
Test a FindBy method that returns non-unique keys.
Modify non-key data in the rows that have non-unique keys.
Enter "U" in the State field for each row that you modified.
This will update the rows.
Use the MultiMaint method to modify the data (after all data is entered).
The data was successfully committed to the database if the State field is now US.
Notes:
Natural Business Services now supplies the SPSERRN2 user exit. This user exit provides more access to error information than the previous SPSERRN user exit and should be used for all new development.
The CDERRLD2 parameter data area used by SPSERRN2 contains the following parameters:
MSG_TYPE (A1) /* MSG_TYPE is the same as 52
ERROR_TYPE (A1) /*from NAT error O- runtime;S- syntax;C-command;T-terminate;T-program terminate;R-remote
MSG_CATEGORY (A3) /*CMB, ETB, CMD, EXX, EXU, NDV,CWI
ERROR_CLASS (N4.0) /*from EXX
ERROR_LIBRARY (A8) /*lib' of module with err
ERROR_PROGRAM (A8) /*from error pgm
ERROR_NUMBER (N4) /*from nat error pgm
ERROR_LINE (I4) /*from Nat error line
ERROR_LEVEL_NBR (N2) /*from Nat error
ERROR_MSG (A250) /*msg text
NBS_SERVICE (A32) /* NBS Business Service
NBS_DOMAIN (A8) /* NBS Domain
NBS_METHOD (A32) /* NBS Method
PROCESS_DESCRIPTION (A32) /* Description of error
ERROR_DATE (A8) /* Date of error
ERROR_TIME (A7) /* Time of error
ERROR_TIMESTAMP (N15.0) /* Timestamp of error
The Delete Broker Log Records by Date panel in the Administration subsystem has changed. You can now delete all communication log file records, instead of just the Broker logs. In previous versions, you could enter "SYSBIZ/MENU/SA/SF/BC" to display the Delete Broker Log Records by Date panel. You can now enter "SYSBIZ/MENU/SA/SF/DC" to display the Delete Communication Log Records by Date panel. This panel allows you to delete all Broker and Natural Development Server log file records.
Note:
If you have scripts that use direct commands to access this panel,
ensure you change the function code in the scripts.
When the attach server is started, multiple dispatchers can now be started automatically. In previous versions a dispatcher started up when needed and shut down when not needed.
This change affects the JCL used to start the attach server. Two extra input parameters have been added to the end of the CMSYNIN data in the JCL: the logical name of the Natural Business Services server to be initiated and the number of instances of that server to initiate.
Note:
To ensure backward compatibility for existing customers, no error
will occur if these values are not supplied.
Tip:
This change is helpful for customers who initiate attach servers via
a started task. To take advantage of this change, remember to supply values for
the new input parameters in the JCL.
Natural Business Services V5.3 is available on Microsoft’s Vista operating system.
Similar to the point in New Functionality for the Object-Browse-Select-Subp Model, if a business service is based on the Object-Browse-Subp model and the records are extremely large, the subprogram proxy will automatically reduce the number of rows to an appropriate size.
When you select the Based on existing subprogram(s) option while generating a business service, two new options are available if the subprogram(s) was generated by Natural Construct. These options let you take advantage of the Business Service wizard’s knowledge of Natural Construct models and allow it to generate default methods for your business service. For information, see:
For the Eclipse plug-in, see Based on Existing Subprogram(s).
For the Natural plug-in, see Based on Existing Subprogram(s).
This section describes the new features and enhancements in Natural Business Services V5.3, service pack 1. The following topics are covered:
When exporting domains, you can now:
Use mixed case for business service names
In previous versions, it was necessary to run a Natural program to
perform a SET CONTROL 'L' command to export business
services with mixed case names. You can now export services with mixed case
names without this additional step.
Use wildcard characters to export a range of services
Export selected services one after another into the same dataset
Export the latest versions only
Export the Natural subprograms that implement the selected business services (via the SYSOBJH Natural utility)
Override the name of the destination library (defaults to the name of the source library)
Export XREF information
These changes affect the BS_EXDOM module.
When importing domains, you can now:
Import the Natural subprograms that implement the selected business services (via the SYSOBJH Natural utility)
Replace existing data with imported data
Import XREF information
Override the name of the destination library (defaults to the name of the source library)
These changes affect the BS_IMDOM module.
Note:
For information, see
Transfer
Domains, Business Services, and Step Library
Chains.
If you use mainframe JCL or Unix scripts to run the Export or Import Domains utilities, you must update your JCL or scripts to use work file 2 when transferring business service data. This change is due to the new feature that uses the SYSOBJH Natural utility to transfer the associated subprogram data. As SYSOBJH requires the availability of work file 1 to transfer the subprogram data, work file 2 is now used to transfer business service data. SYSOBJH produces a report listing the unloaded associated subprograms, which is saved as a text member named NBSDPLOY in the WORKPLAN library.
Note:
The business service data is not synchronously loaded with the
associated subprograms. If the execution is cancelled, the loaded business
service data may be out of synch with the subprogram data. If this occurs,
restart the import process from the beginning.
You can use a batch job to delete business services and their associated modules. In addition, a warning message is now displayed when deleting a service.
You can now change your server password from the client.
The NBS Tester now includes help information.
This section describes changes to Natural Construct in this version of Natural Business Services. The following topics are covered:
In this version, the CSTnnn.INPL dataset also loads the Natural Construct error messages. In previous versions, these error messages were contained in the CSTnnn.ERRN dataset. This change applies to Unix and mainframe platforms.
Note:
When installing both products, you must now install
Natural Construct before installing
Natural Business Services.
You can now produce a report listing the modules that have been copied by the CVUSRCOP utility. To do this, enter "CVUSRCOP y" when invoking the utility from the client.
The CDACTL local data area (LDA) generated by the Browse-Select-Subp model can now include up to 16 customized actions (in addition to the 14 that are generated by default). This data area can now contain up to 29 actions, (including the flip option in CDACT, which brings the total to 30).
Note:
The 13 standard actions must not be changed (#ADD, #BROWSE, #CLEAR,
#DISPLAY, #MODIFY, #NEXT, #PURGE, #COPY, #RECALL, #REPLACE, #SELECT, #DETAIL,
and #FORMER).
To include additional actions:
Increase the #USED-CODES variable in CDACTL (13, by default).
Recompile CDACT.
For more information, see Add an Action in Defining Actions for Generated Applications in Natural Construct Generation.
The Natural MULTI-FETCH clause is now available for the Browse, Browse-Select, and Object-Browse series of models. The generated browse and browse-select subprograms now estimate the optimized number of rows to return at one time and the generated object browse subprogram uses ROWS-REQUESTED to optimize the number of rows to fetch.
Note:
Code frame CS-BB9 and the CUBOGEN subprogram were modified to
accommodate these changes.
The layout for input fields generated by the Browse model is more logical and easier to understand. In previous versions, the Sequence variable was placed between the #input fields and any additional input parameters. This variable is now placed after all input fields, including any additional parameters.
Using CSXDEFLT and CSUGETDF, you can override default values for the Object-Browse-Dialog model, such as the Generate language or Application library used. For information, see Use CSXDEFLT Overrides.
By default, subprograms generated by the previous Object-Browse-Select-Subp model created 20 rows of data. For extremely large records, however, 20 rows may be too large for the network. To compensate for this, the subprogram automatically reduces the number of rows until it reaches an appropriate size. This allows the Business Service wizard to create an appropriately sized business service.
For DB2 users, this model now generates the SELECT-STATEMENTS user exit for each logical key (L1 to L6). This user exit generates a SELECT statement for SQL files. For more information, see User Exits for the Generation Models in Natural Construct Generation.
Natural Construct now generates D (date), T (time), and TS (timestamp) formats for DB2. Previous versions generated these formats as Alpha fields.
When the generation defaults for a DDM have the value “D” for Date/Time/Timestamp representation, Predict generates D, T, and TS formats (respectively). Natural Construct acknowledges this default and also generates D, T, and TS formats.
Note:
When the generation defaults for a DDM have the value “A”, both
Predict and Natural Construct generate A10, A8, and A26 formats
(respectively).
This section describes enhancements to the Object-Maint-Subp model.
Note:
For information on another new feature, see
Use *ISN as the Unique Primary Key
for Maintenance.
The following topics are covered:
If the Predict view field is blank on the Additional Parameters panel for the Object-Maint-Subp model, and there is a value in Object PDA, you can enter the name of another PDA (which must be generated by Natural Construct and be available in the current library) in Object PDA to populate the Predict view, Primary key, and Object name fields with the values from this PDA.
An object maintenance subprogram generated by the Object-Maint-Subp model now stores a “before” image of data (for example, what an order looked like before a user made changes). The before image is kept on the database and is requested before an update is performed.
To enable this functionality, the code must be generated with the Hash Locking option. When this option is specified, a local data area is created that is identical to the object PDA except Logical values are stored as Alpha formats. This allows two copies of the object to exist: the user-modified version and the original database version. When the user-modified data is ready to be committed to the database, the original database version is retrieved to determine if any changes have been made since the user initially saw the data.
This functionality is accomplished using a hashing algorithm. When the data is initially retrieved from the database, it is put through a hashing algorithm and hashed to a number stored in the restricted PDA. When the data is retrieved from the database a second time, it is again hashed to a number and the two numbers are compared. If the data has changed since the user initially saw it, the #HASH-RETRIEVE and #HASH-DATABASE variables will contain different values. If the numbers are the same, the data in the local data area contains the initial values.
Tip:
As the local data area is populated with the original data, you can
use this data in your own logic.
The Object-Maint-Subp model generates the following new user exits:
AFTER-STORE
AFTER-UPDATE
BEFORE-DELETE
BEFORE-STORE
For information, see User Exits for the Object-Maint-Subp Model.
Note:
Code frame COBC9 was modified to accommodate these changes.
In addition, the Object-Maint-Subp model generates the BEFORE-ET user exit. It is similar to the BEFORE-ET-PROCESSING user exit, except the code will be executed whether an ET was issued or not.
Note:
Code frame COBB9 was modified to accommodate these
changes.
The Object-Generic-Subp model generates the following new user exits:
AFTER-CODE
BEFORE-CODE
MATERIALIZE-XARRAY-LDA-TO-PDA
MATERIALIZE-XARRAY-PDA-TO-LDA
MOVE-BACK-UNCATEGORIZED
MOVE-TO-UNCATEGORIZED
PARAMETER-DATA-UNCATEGORIZED
RESET-TEMP-MATERIALIZED
UNDEFINED-METHOD
For information about these exits, see User Exits for the Object-Generic-Subp Model.
The Natural Construct Administration and Modeling guide is now available in html format.
The CSHUNLD utility now unloads an unlimited number of help text members.
This section describes the new features and enhancements in Natural Construct V5.3, service pack 1. The following topics are covered:
When Program View is selected for an object-browse subprogram (generated using the Object-Browse-Subp model), you can specify a Predict view to derive a subset of the fields in the row PDA (as opposed to manually creating the view in a user exit).
This section describes the new features and enhancements in this version of the Natural Business Services Eclipse plug-in. The following topics are covered:
Eclipse Ganymede (3.4) is now supported, in addition to Eclipse Europa (3.3).
Note:
To install the NBS plug-in on Eclipse Ganymede, see
Install
Plug-in for Eclipse Ganymede (3.4).
Axis and CentraSite deployment for Web services has been removed from Natural Business Services. This functionality has been replaced with the WS-Stack plug-in functionality. For information, see Set Web Services Stack Preferences.
Note:
The WS-Stack plug-in will not add an association between a Web
service being added to CentraSite and the NBS repository metadata in
CentraSite. You must add each association manually. For information, see
Add
CentraSite Associations.
You can now add Natural Business Services repository metadata to CentraSite. For information, see Access CentraSite.
Users can now cache their security credentials by selecting Save credentials in the NBS logon window. To remove saved credentials from the security cache when Eclipse shuts down, select one of the following options:
To clear logon credentials for the current connection, open the context menu for the connection in the NBS Repositories view and select .
To clear logon credentials for all connections, open the context menu for the Connections node and select .
You can now export Natural Business Services repository metadata to an XML file. For information, see Export Repository Metadata to XML.
The Eclipse plug-in now includes a wizard to create a Natural REQUEST DOCUMENT client. For information, see Create a REQUEST DOCUMENT Client.
When deploying Web services from the Eclipse plug-in to an external web server (for example, tomcat), it is now possible to enable logging. Debug log statements will be generated into each Web service method that corresponds to the business service methods. For information, see Generate log4j Log Statements.
This section describes the new features and enhancements in Eclipse plug-in for Natural Business Services V5.3, service pack 1. The following topics are covered:
Java 5 or higher and Eclipse 3.3 or 3.4 are required to use the Eclipse plug-in.
When testing a business service based on Natural Construct models, the test window has changed. Irrelevant information is no longer available and more detailed information is provided when required. For information, see Test a Business Service.
The NBS Preferences window has been enhanced. For information, see Set Natural Business Services Preferences.
Logging and tracing is now done using log4j technology. Trace options and settings that were previously defined at the bottom of the repository view have been replaced with a button that displays the tracing properties file for editing. For information, see Set Trace and Log Options.
Note:
Instructions to edit the properties file are included in the
file.
New preference options are available in the Eclipse Preferences window to help format the log and trace output. For example, you can change the colors used in the NBS console to indicate different levels in the trace output. You can also assign a different color to each logger displayed in the Preferences window (the logger names are derived from the log4j.properties file). For information, see Preferences for Trace and Log Functions.
The repository explorer is only refreshed when certain settings are changed. Other changes include the ability to not refresh the view and to keep connections open.
When deploying a business service, the following options are now available:
Deploy the associated subprograms
Maintain all Xref information
These changes affect the BS_EXDOM and BS_IMDOM modules. For information, see Deploy a Business Service.
When creating a business service, you can define the service by using a custom code generation model. This option now supports lookups options for fields (for example, for Predict files) and allows you to specify which fields to request from the user. For information, see Define Lookup Values.
On non-English XP machines, the Application Data folder may have been translated into the host language (for example, “Datos de uso” in Spanish). This caused the internal Axis server to fail upon startup because “Application Data” was not found on the machine.
To fix this problem, environment variables now determine the Application Data folder for the “Current” and “All” user profiles and then check for the Axis2 folder in the Application Data folders (i.e., Software AG/Natural Business Services/axis2/). The Current user folder is checked first and then the All users folder is checked.
Once the Axis folder is found, it will be used as the root to start the Axis server. This allows the Axis server to be started up like any other Java application within Eclipse. For example, you can start up the internal Axis server, deploy a Web service, set a break point in source code, and Eclipse will stop on that line of code during the execution of the Web service.
The following table lists the guides in the Natural Business Services documentation set:
| Document | Description |
|---|---|
| Natural Business Services Installation on Mainframes | Describes the installation of Natural Business Services on mainframe platforms. |
| Natural Business Services Installation on Unix | Describes the installation of Natural Business Services on Unix platforms. |
| Natural Business Services Installation on Windows | Describes the installation of Natural Business Services on Windows platforms. |
| Natural Business Services Getting Started | Provides information to help new users of Natural Business Services. |
| Natural Business Services Administration | Describes how to set up and manage environments
for Natural Business Services applications. This
guide is intended for:
|
| Understanding Natural Business Services | Provides information on how Natural Business Services creates business services. |
| Natural Business Services Natural Plug-in | Describes the Natural plug-in supplied by Natural Business Services. This guide is intended for developers who are familiar with Natural for Windows and the Natural Development Server (NDV) and want to use the Natural Business Services plug-in to create and maintain business services. |
| Natural Business Services Eclipse Plug-in | Describes the Natural Business Services plug-in for Eclipse. This guide is intended for developers who are familiar with Eclipse and want to use the Natural Business Services Eclipse plug-in to create Natural business services, Web services, web applications, and/or generate client proxy classes to access business services. |
| Natural Business Services Visual Studio Add-in | Describes the Natural Business Services add-in for Visual Studio. This guide is intended for developers who are familiar with Visual Studio and want to use the Natural Business Services Visual Studio add-in to create Web services, web applications, and/or generate client proxy classes to access Natural business services. |
| Natural Business Services Tools and Utilities | Describes the development tools and utilities provided by Natural Business Services: the Broker Driver program, NBS Tester, and Server Monitor. |
| Natural Business Services Subprogram-Proxy-Client Model | Describes the Natural Business Services Subprogram-Proxy-Client model. This model generates a subprogram proxy to access a Natural subprogram. |
| Natural Construct Administration and Modeling | Describes how to access and use the Administration subsystem of Natural Construct. |
| Natural Construct Object Models | Describes the Natural Construct Object models. These models generate the Natural subprograms used by Natural Business Services. |
| Natural Construct Transform-Browse Model | Describes the Natural Construct Transform-Browse model. This model transforms an existing browse module (generated by the Browse, Browse-Select, Browse-Select-Subp, or Browse-Subp model) into object-browse modules (generated by the Object-Browse series of models). |