The Master Data Model for Veteran Care

Developer Documentation » VDM » Remote_Procedure-8994

Remote Procedure (8994)

This file is used as a repository of server-based procedures in the context of the Client/Server architecture. By using the Remote Procedure Call (RPC) Broker, applications running on client workstations can invoke (call) the procedures in this file to be executed by the server and the results will be returned to the client application. Each remote procedure entry is associated with an entry point (ROUTINE with optional TAG). Calls to these procedures can include parameters of different value types. The resulting value of the call can be either a string, a list of strings or a word processing string as indicated by the RETURN VALUE TYPE field (.04). The remote procedure may be available for use by anyone or its use may be restricted to one or more application. The range of availability is indicated by the AVAILABILITY field. IF THERE IS NO ENTRY IN THE AVAILABILITY FIELD, then the procedure is assumed to be PUBLIC. A remote procedure may be removed from service for a period of time by setting the INACTIVE field. A request for use of a procedure which is marked inactive will result in an error being returned to the originating application.

Global: ^XWB(8994,

Domain: Non-Clinical

Properties

Label/Field Name Field # Description Datatype Attributes Range
Name
  name
.01   STRING INDEXED
REQUIRED
 
Tag
  tag
.02   STRING    
Routine
  routine
.03   STRING REQUIRED  
Return Value Type
  return_value_type
.04 This field tells RPC Broker how to process the resulting data from the call.

SINGLE VALUE: Broker will return the value of the return parameter (first
parameter in the formal list). For example,
TAG(RESULT) ;
S RESULT=”DOE, JOHN”
Q

ARRAY: Using $ORDER Broker will traverse the return parameter (first
parameter in the formal list), returning all elements of the array.
For example,
TAG(RESULT) ;
S RESULT(1)=”ONE”
S RESULT(2)=”TWO”
Q

WORD PROCESSING: This type is treated exactly the same way as the ARRAY,
with one exception that the WORD WRAP ON field is used to
control whether each line returned is terminated with CR + LF characters.
See WORD WRAP ON field description for more information.

GLOBAL ARRAY: Return value parameter should be set to a closed global
reference in ^TMP. The global’s data nodes will be traversed using
$QUERY, and all data values on global nodes descendant from the global
reference are returned. This type is especially useful for returning data
from VA FileMan word processing fields, where each line is on a
0-subscripted node.

Important: The global reference you pass is killed by the Broker at the
end of RPC Execution as part of RPC cleanup. Do not pass a
global reference that is not in ^TMP or that should not be
killed.

This type is useful for returning large amounts of data to the client,
where using the ARRAY type can exceed the symbol table limit and crash
your RPC.

For example, to return sign-on introductory text you could do this,
TAG(RESULT) ;
M RESULT=^XTV(8989.3,1,”INTRO”)
K RESULT(0) ;this node is not needed
Q

GLOBAL INSTANCE: Using this type Broker will return the value of a global
node. For example the following code will return the whole 0th node
from the NEW PERSON file for the current user.
TAG(RESULT) ;
S RESULT=$NA(^VA(200,DUZ,0))
Q
ENUMERATION REQUIRED GLOBAL INSTANCE: 5
ARRAY: 2
SINGLE VALUE: 1
GLOBAL ARRAY: 4
WORD PROCESSING: 3
Availability
  availability
.05 This field is used to indicate the availability of the API to various
users.

PUBLIC indicates that the API is available for general use by any package,
and it is not necessary to either indicate that the API is being used or
to request permission to use it.

SUBSCRIPTION indicates that the API is available to those packages that
wish to use it, BUT the package needs to indicate that it is using the API
or subscribing to it.

AGREEMENT indicates that the API is available to packages, other than the
developing package, only by means of an integration agreement on its
usage.

RESTRICTED indicates that the API is not available for reference by any
package other than the package which developed it. Entry of the input and
return parameter information is at the option of the developing package in
this case.
ENUMERATION   RESTRICTED: R
AGREEMENT: A
PUBLIC: P
SUBSCRIPTION: S
Inactive
  inactive
.06 This field is used to indicate that the RPC is not available for use for
some reason. An RPC can be marked as completely unusable (1), unusable
locally (2), or unusable remotely (3). Local use means in the account the
user is logged into; remote use means in an account other than the one the
user is directly logged into (i.e., a ‘Remote RPC’). The Broker will not
run an RPC that is marked as unusable in the applicable context.
ENUMERATION   ACTIVE: 0
REMOTE INACTIVE (ACTIVE LOCALLY): 3
INACTIVE: 1
LOCAL INACTIVE (ACTIVE REMOTELY): 2
Client Manager
  client_manager
.07 This field is used to identify those APIs which may be initiated to
control the client or to send data to the client unrelated to requests
from the client. These actions usually require additional information on
the configuration which is present.
BOOLEAN   true: 1
Word Wrap On
  word_wrap_on
.08 Affects GLOBAL ARRAY and WORD PROCESSING return value types only. If set to
FALSE, all data values are returned in a single concatenated string in
Results[0]. If set to TRUE, each array node on the M side is returned as a
distinct array item in the Results property of the TRPCBroker.

If you’re returning some text to the client and you’d rather let the
memo box of the client control the wrapping of lines, set WORD WRAP ON
to FALSE. On the other hand, if you want to preserve line breaks as they
exist on the server, set WORD WRAP ON to TRUE.
ENUMERATION   TRUE: 1
FALSE: 0
Version
  version
.09 A number to identify the version of the Remote Procedure. Currently this
number is only checked if the Remote Procedure is being run on a foreign
server. If a version number is passed to the Broker by the application
requesting that the Remote Procedure be run on the foreign server, the
Remote Procedure will only be run if the value of this field is equal to
or greater than the passed version number.
NUMERIC    
Suppress Rdv User Setup
  suppress_rdv_user_setup
.1 This field controls how Remote Data View handles the setup of a user to
run the RPC. If the field is set to No or is blank than the remote users
data will be set up in the New Person file and DUZ for the process will be
set to the user. If the field is set to Yes at the remote site the remote
user data will NOT be entered into the New Person file and DUZ will be set
to the Postmaster.

This field should not be set to Yes for RPC’s that collect patient data.
If there is any question about why a RPC has this set to yes contact the
DBA for the VA.
BOOLEAN   false: 1
true: 0
App Proxy Allowed
  app_proxy_allowed
.11 This field must be set to Allowed if this RPC is to be run by an
APPLICATION PROXY user.
The default is to NOT allow access.
BOOLEAN   false: 1
true: 0
Description
  description
1   STRING    
Input Parameter
  input_parameter
2 Input parameter is what RPC Broker passes into your remote procedure. The
name that you may call the input parameter has no special meaning to the
Broker. However, you should choose a name that best describes the data
that the parameter is used for.
OBJECT   Input_Parameter-8994_02
Return Parameter Description
  return_parameter_description
3   STRING    

↑ Return to top

Sub-Files

Input Parameter (8994.02)

ID
Input_Parameter-8994_02

Properties

Label/Field Name Field # Description Datatype Attributes Range
Input Parameter
  input_parameter
.01 This field is used to identify an input parameter for the API. STRING INDEXED
REQUIRED
 
Parameter Type
  parameter_type
.02 This field is used to indicate the type (Literal, List, Reference, or Word
Processing entry) of value passed by this parameter. The Literal, List,
and Reference types correspond to the TParamType of the same name. A Word
Processing type would also be a List TParamType.
ENUMERATION   LITERAL: 1
LIST: 2
REFERENCE: 4
WORD PROCESSING: 3
Maximum Data Length
  maximum_data_length
.03 This field indicates the maximum length that would be expected for the
parameter value.
NUMERIC    
Required
  required
.04 This field is used to indicate that the input parameter is a required
argument in the API call.
BOOLEAN   false: 0
true: 1
Sequence Number
  sequence_number
.05 This number should correspond to the position of this parameter in the
formal list of the function. Consider that the return parameter that
Broker passes in, by reference, is the very first parameter with the
sequence number of 0. The next parameter is the first application-supplied
parameter with the sequence of 1.

Example:

Your entry point may look like:

EN(RESULT,USER,DATE) ;this will do something

In this case the parameter corresponding to USER should have sequence
number 1 and the DATE parameter should be 2.
NUMERIC INDEXED  
Description
  description
1   STRING    

↑ Return to top


Document generated on August 31st 2017, 2:55:41 pm