Service Group Application Reference

10.5
- 10.5 HotFix 2
- 10.5 HotFix 1
- 10.2 HotFix 1
- 10.2
- 10.1
- 10.0 HotFix 1
- 10.0

Back Next

Calling a Service

The above Services are user-defined in a structure called the Service Group definition file. For information on how to define and customize Services and the Algorithms that they are linked to, see the

DEFINITION and CUSTOMIZATION GUIDE FOR SSA-NAME3 SERVICE GROUPS

Once the Service Group and other Definition Files have been customized, they are passed through a process known as Generation to produce a Service Group Data File. For more details on Generation, see the

GENERATION and TESTING GUIDE FOR SSA-NAME3 SERVICE GROUPS

After Generation, the generated Service Group Data File is transferred to the target system. For the purposes of this manual it will be referred to simply as the Service Group.

A SSA-NAME3 Service is invoked by an application by Calling the Service Group and specifying the name of the Service required.

On MS Windows the program will call a dynamic link library and on Unix it will call a shared object. These in turn call the Service Group Data File.

An environment variable SSAUSGDIR needs to be set to reference the location of the Service Group Data File and the SSA-NAME3 binaries directory needs to be specified in the system search path. For example, on Microsoft Windows platforms:


set SSAUSGDIR=c:\InformaticaIR\ssaname\myusa
set PATH=%PATH%;c:\InformaticaIR\bin

On Unix this may look like:


SSAUSGDIR="$HOME/InformaticaIR/ssaname/myusa"
export SSAUSGDIR
PATH="$PATH:$HOME/InformaticaIR/bin"
export PATH

You should also make sure that the dll or shared object is available within the system search path.

All Services are called in a similar manner. The first two parameters are the Service name and the Response Code. A third parameter that is always required is the Work-area, however, its position in the parameter list varies between Services. The Service Group’s entry point expects twelve parameters.

If a particular service accepts less than twelve, the Call should pass additional ’dummy’ parameters to ensure that all twelve parameters are filled in.

The dummy parameters do not carry any information and can be defined as short as the programming language allows. For example, in Cobol a

PIC (X)

field is adequate; in C,

NULL

fields can be passed.

For example,


01 DUMMY           					PIC X.

CALL ’N3SGUS’ USING SSA-NAME3-SERVICE-NAME,
                         SSA-NAME3-RESPONSE-CODE,
                         P3,
                         P4,
                         P5,
                         P6,
                         P7,
                         P8,
                         P9,
                         SSA-NAME3-WORK-AREA,
                         DUMMY,
                         DUMMY.

or,


n3sgus (ssa_name3_service_name,
        ssa_name3_response_code,
        p3, p4, p5, p6, p7, p8, p9,
        ssa_name3_work_area, NULL, NULL);

Following is a description of the parameters common to all Services, i.e. the Service Name, the Response Code, and the Work-area. Each Chapter in this manual deals with a different Service and describes the exact parameters that are required for that Service.

Service-Name

The Service-Name is the name assigned to a Service type as defined in the Service Group Definition File. The Service Name format can either be a fixed 8 character name (shorter names must be padded with spaces to 8 characters in the parameter list) or a variable name up to 32 characters surrounded with asterisks.

The person responsible for customizing SSA-NAME3 should be able to supply the names of the available Services; however, it is generally up to the analyst/programmer to understand what these Services are providing.

Response-Code

The Response code is a 20 character string, where the first two characters are the error number. Some services only use the 2-character Error number in the parameter list and in these cases the full 20 character response code is found in the Work-area. Others, specifically the NAMESET, TRACE and INFO Services use the full 20-character response code in the parameter list.

A value of

in the Error number field always indicates a successful completion. The non-zero values are documented in the

Response Codes

chapter of this manual. This chapter also describes the layout and the correct way to interrogate Response Codes.

Work-area

One of the other parameters always required is the Work-area. This is an application memory block that the Service uses as a scratch-pad. Some Services may return information in this area but most just use it as temporary working memory. The size required may differ from Service to Service and from SSA-NAME3 release to release. A minimum of 30,000 bytes is recommended. To set this value more accurately, you can get the size from the output

WSIZE

of a Testbed run.

The structure of the Work-area is as follows:

Offset	Length	Contents
0	42	reserved
42	20	Extended Response Code
62	6	Work-area size (zoned numeric with leading zeros). This field will only be checked if the PASSING WORKAREA-SIZE flag has been set in the Service Group Definition. Refer to the Service Group Definition section of the DEFINITION and CUSTOMIZATION GUIDE FOR SSANAME3 SERVICE GROUPS for more details.
68	6	Offset to Matching Method-table (offset from this position). This is applicable for the MATCH Service only.

Rename Saved Search

Table of Contents

Service Group Application Reference

Service Group Application Reference

Calling a Service

Calling a Service

Service-Name

Response-Code

Work-area