Child pages
  • USAS-AR Subsystem Interfacing ARF with other databases
Skip to end of metadata
Go to start of metadata

Introduction

The USAS/AR subsystem (ARF and AR report programs) provides a dynamic interface for accessing customer names and addresses. ITC personnel may write interface modules which ARF can call to search for customers and return customer name and address from a non-state software file.

ITC staff may write these routines to allow their users to access any potential customers in any file which contains an identifier, name and address information. For example, you might write an interface module to access student names and addresses from your districts' student information system. Or, if you use a payroll system other than USPS, you could write a module to get names and addresses from that system.

The integration with ARF is seamless once the interface modules are written. Users in ARF can access the customer information simply by using the prefix you assign. For instance, if you use the customer prefix of "S" for students, the user enters "S" as a prefix when dealing with student customers.

Preparing an Interface Module

Basics

To write an interface module for use in ARF, you must write two routines. One which ARF will call when the user presses the [Find] key. This routine will be passed the string to search
for and must perform an appropriate lookup and return matching customer names. The second routine will be called whenever ARF needs to display the customer name and address. This routine will be passed the customer number and your routine must return the name and address (or appropriate error status). The specifications for these routine are contained in later sections of this document.

Your programs will be linked into a VMS sharable image. When the user enters the prefix you've chosen, ARF will dynamically link to the sharable image and invoke your routines.

You will need to choose a character to use as the "prefix" for the customer. USAS/AR currently defines three prefixes: C for AR customers, V for USAS vendors and E for USPS employees. You must not duplicate one of these standard prefixes. Also, if you develop an interface module which uses a specific prefix, please register it with the SSDT by sending mail to mail_ssdt@nwoca.ohio.gov. If the SSDT adds additional standard prefixes in the future, we will attempt to avoid duplicating prefixes that DAS's have defined.

The prefix S is already reserved for use by DAS sites for use as a student prefix. You do not need to register S as a prefix as the SSDT will never use that prefix.

Requirements

In order for your routines to interface correctly with ARF, they must meet the requirements below:

  • ARF requires that customer numbers be entirely numeric and zero filled to nine digits. If the source system you are writing routines for uses alphanumeric identifiers, then your routines must convert them to numeric in a fashion which guarantees uniqueness.
  • The interface modules may be written in any language which supports the OpenVMS Procedure Calling Standard. Specifically, it must be able to pass fixed length fields by reference.
  • The modules should not use any global or external sections. If they do, you must customize the linker options file to modify the appropriate PSECT such that they are not shared writable sections.
  • Care should be taken to write the modules such that they are as efficient as possible. For example, they should only open data files on the first call (rather than on every call). ARF and the report programs may call your modules hundreds of times during a typical run. Any performance problems in your modules may affect ARF significantly.

Building the Sharable Image

After you have written the appropriate modules, you must prepare them by linking them into a sharable image. To do this, it is recommended that you use OECN$BUD:AR_LINK_CUSTOM.COM included with the software distribution. This command procedure will link your .OBJ file into a sharable image suitable to ARF. See the comments in AR_LINK_CUSTOM.COM for more information about linking the image.

Making image available to ARF

After preparing the sharable image, you must define a special logical to make the image and new prefix available to ARF. The logical OECN$AR_CUSTOMER_x (where x is the prefix the user will use in ARF) must be defined to point to the sharable image.

First place the sharable image in a common location available to end-users. The protection on the image must be W:RE. Then define OECN$AR_CUSTOMER_x to point to it. For example, if you are writing an interface module for an S prefix, define the logical as:

$ DEFINE OECN$AR_CUSTOMER_S OECN$CUSTOM:OECN$AR_CUST_S.EXE

Testing

Building the sharable image and defining the logical must also be done while writing and testing your modules. After defining the logicals, you can run ARF to test your routines. If you find this process inconvenient, send mail to mail_ssdt@nwoca.ohio.gov and request a copy of TESTCUST.COB. This is a test harness program which provides a simplied interface to the OECN$AR_CUST_xx routines. It performs the calls in the same manner as ARF but is easier to use while testing. You can also link this program to your routines directly (rather than as a sharable image) to allow use of the VMS Debugger.

This routine will accept a prefix and customer number and return the
customer name, address, etc.

Format

OECN$AR_CUST_GET customer-prefix


customer-number
prefix-description
call-status
call-message
name
attention
address1
address2
city
state
postal-code
phone
status

RETURNS

none

Arguments

customer-prefix

VMS usage:

fixed string

type:

fixed 1 character string

access:

read

mechanism:

by reference

Customer prefix

customer-number

VMS usage:

fixed string

type:

fixed 9 character string

access:

read

mechanism:

by reference

Customer number. Must be right justified and zero filled.

prefix-description

VMS usage:

fixed string

type:

fixed 10 character string

access:

write

mechanism:

by reference

Customer number. Must be right justified and zero filled.

call-status

VMS usage:

fixed string

type:

fixed 2 character string

access:

write

mechanism:

by reference

Status of call. Indicates success or failure status of call. Must
contain one of the following values:

00

Successful

10

Invalid or unknown prefix value

11

Customer not found

If status other than "00" is returned, then the contents of the customer fields are undefined.

call-message

VMS usage:

fixed string

type:

fixed 30 character string

access:

write

mechanism:

by reference

Short description which further defines reason for failure of call.

name

VMS usage:

fixed string

type:

fixed 34 character string

access:

write

mechanism:

by reference

Customer name. Preferably in order which is sensible to sort by, i.e.
last name then first name.

attention

VMS usage:

fixed string

type:

fixed 34 character string

access:

write

mechanism:

by reference

Attention line or customer second name. May be left blank.

address1

VMS usage:

fixed string

type:

fixed 34 character string

access:

write

mechanism:

by reference

First line of address.

address2

VMS usage:

fixed string

type:

fixed 34 character string

access:

write

mechanism:

by reference

Second line of address.

city

VMS usage:

fixed string

type:

fixed 18 character string

access:

write

mechanism:

by reference

City

state

VMS usage:

fixed string

type:

fixed 4 character string

access:

write

mechanism:

by reference

State

postal-code

VMS usage:

fixed string

type:

fixed 10 character string

access:

write

mechanism:

by reference

Postal code. Should be returned edited appropriately for type of postal
code (e.g. edited with hyphen for zip+4).

phone

VMS usage:

fixed string

type:

fixed 18 character string

access:

write

mechanism:

by reference

Phone number, edited.

status

VMS usage:

fixed string

type:

fixed 1 character string

access:

write

mechanism:

by reference

Status of customer. Must be one of the following:

A

Active

I

Inactive

space

unknown

Description

This routine will accept a prefix and customer number and return the customer name, address, etc. The routine is expected to return a successful status and the customer information or an error status.

This routine should not perform any terminal I/O. Any error messages should be returned in the field provided.

COBOL programmers may copy OECN$LIB:ARCUSTGET.LIB into the LINKAGE section to define the arguments for this routine.

This routine perform a search for customers based on a search string,
most likely customer name.

Format

OECN$AR_CUST_FIND customer-prefix


search-function
search-string
prompt-string
call-status
call-message
customer-number
customer-name

RETURNS

none

Arguments

customer-prefix

VMS usage:

fixed string

type:

fixed 1 character string

access:

read

mechanism:

by reference

Customer prefix.

search-function

VMS usage:

fixed string

type:

fixed 1 character string

access:

read

mechanism:

by reference

Indicates function the routine is to perform. Will be one of:

Function Description

P

Return prompt string to be used for searches with this prefix. ARF will call the routine with this function prior to prompting the user for the search string.

F

Find and return the first customer matching the search string

N

Return next customer, the customer returned may be the next one along the same key, or may be the next customer which matches search string as desired by the source system.

search-string

VMS usage:

fixed string

type:

fixed 40 character string

access:

read

mechanism:

by reference

Search string that should be used to find matching customer. Will be
passed for both functions F and N.

prompt-string

VMS usage:

fixed string

type:

fixed 30 character string

access:

write

mechanism:

by reference

String that ARF should use when prompting user for a search string for
this customer type. (e.g. "Enter student name: ").

call-status

VMS usage:

fixed string

type:

fixed 2 character string

access:

write

mechanism:

by reference

Status of call:

00

Successful, customer found

10

Invalid or unknown prefix type

11

no matching customer found

12

end of file or no more matches

call-message

VMS usage:

fixed string

type:

fixed 30 character string

access:

write

mechanism:

by reference

Brief message which further describes reason for unsuccessful status.

customer-number

VMS usage:

fixed string

type:

fixed 09 character string

access:

write

mechanism:

by reference

Customer number of matching customer. Must be numeric, right justified
and zero filled. Value is undefined if status is not successful.

customer-name

VMS usage:

fixed string

type:

fixed 34 character string

access:

write

mechanism:

by reference

Name of customer found. May also contain other information about
customer to assist user in identifying correct customer (e.g. a
building code).

Description

COBOL programmers may copy OECN$LIB:ARCUSTFIND.LIB into the LINKAGE section to define the arguments.

This routine will find a customer given a prefix and search string. The actual search method is be dependent on the source system for the search. ARF will call this routine to perform one of three functions:

  1. Prompt function. ARF calls with this function when it is preparing to prompt the user for a search string. The text that OECN$AR_CUST_FIND returns in the prompt-string argument will be used to prompt the user. For example, if looking up student's the routine might return "Enter student name to find:" as the prompt string.
  2. Find function. ARF calls with this function to find the first matching customer for a given search string. The routine must attempt to locate a match and return the customer number and name. The routine is expected to maintain its own context for a subsequent "Next" call.
  3. Next function. ARF calls this function to return the next matching customer. This function will only be used after a successful Find function has been performed. ARF will call with this function repeatedly until the routine returns an unsuccessful status or until ARF has acquired a sufficient number of matches.

This routine should be careful to maintain it's own search context, but should not make assumptions about the order in which ARF will call it. The routine may assume that Next function will only be invoked after a successful Find. But beyond that, the functions may be invoked in any order and repeatedly.

  • No labels