In BASIC+, a service is a stored procedure that can do more than one thing. This is accomplished via a parameter that indicates what functionality, or service, you want done. Services have been around for a long time, as evidenced by built-in routines such as Utility or Repository. Services reduce clutter in your repository and make it easier to find the functionality you need. This convenience is significantly increased for SRP Editor users since the tool uses service metadata to provide useful prompts and parameter information.

Creating a Service

Creating a service is easy. From the File menu, select New, then New Item. Or use the Ctrl+N shortcut. This will display the New Item dialog. Click Service Module.

This will create an empty service module. It won't compile yet because we don't have any services. The first thing we'll want to do is do a Find and Replace (Ctrl+H) on the {Name} placeholder. Name it whatever you want. Note that _Services will be the suffix for this routine. This is our recommended naming convention as it cues the developer that there is going to be metadata associated with it, and that it will provide an array of functionality.

Defining a Service

The Enhanced BASIC+ syntax for a service uses the Service keyword:

Service GetCustomerAddress(AddressType)
    Begin Case
        Case AddressType _EQC "Mailing"  ; Response = CustRec<MAILING_ADDRESS$>
        Case AddressType _EQC "Shipping" ; Response = CustRec<SHIPPING_ADDRESS$>
        Case AddressType _EQC "Plant"    ; Response = CustRec<PLANT_ADDRESS$>
    End Case
End Service

Service AddSalesTax(ref Amount)
    Amount += (Amount * CustRec< TAX_RATE$ >)
End Service

The SRP PreCompiler recognizes the Service keyword followed by a name and parameter list, which will get converted into a standard GoSub followed by assignments of the generic parameters (Param1–ParamN) to the ones named in the parameter list.

Service parameters are passed by value, not by reference. This is because behind the scenes, Param1 gets copied into the first named variable, such as AddressType. Since the service only has a copy, any changes made to it will not pass back up to the caller. If you need a parameter’s changes to persist back to the caller, then precede it with the Ref keyword as seen in the AddSalesTax service above. This will ensure that the referenced parameter is copied back to its original Param when the service is done so the calling routine gets the changes.

Service Metadata

When you compile your stored procedure, a record will be added SYSENV containing all the services and their parameters. This allows the SRP Editor to display this information later to the developer for easy referencing.

Another feature of service modules is the Options keyword. Options tell the SRP Editor to show a dropdown list of options for a parameter.

Options ADDRESSTYPES = "Mailing", "Shipping", "Plant"
Service GetCustomerAddress(AddressType=ADDRESSTYPES)
    Begin Case
        Case AddressType _EQC "Mailing"  ; Response = CustRec< MAILING_ADDRESS$ >
        Case AddressType _EQC "Shipping" ; Response = CustRec< SHIPPING_ADDRESS$ >
        Case AddressType _EQC "Plant"    ; Response = CustRec< PLANT_ADDRESS$ >
    End Case
End Service

The Options keyword can appear anywhere in your code, and its sole purpose is to let you add more metadata to your service. In our example, the developer has three options for the AddressType parameter. So first we defined the list of options and gave it a name: ADDRESSTYPES. Then we assigned it to our service’s AddressType parameter using the equal operator. Now when the user presses a quote character, the list of address types will appear.

Jumping to the Service

Note that the new service module added the GoToService statement. This statement will handle everything needed to jump to the service the developer is calling. If the caller passes a service name that does not exist, it is ignore. However, if you want to handle such cases, you can modify the GoToService statement like so:

GoToService else
    // Service doesn't exist, so do something here
end