ROSE OPERATION and ERROR

---

ROSE stands for "Remote Operations Service Element" and defines a request/response transaction protocol in which requests to a conforming entity must be answered with the result or errors defined in operation definitions. Variations of this are used in a number of protocols in use today including CSTA and TCAP.

The definition of the ROSE OPERATION MACRO that is built into the ASN1C90 version of the compiler is as follows:

OPERATION MACRO ::=             
 
BEGIN
 
  TYPE NOTATION           ::= Parameter Result Errors LinkedOperations
 
  VALUE NOTATION          ::= value (VALUE INTEGER)
 
  Parameter               ::= ArgKeyword NamedType | empty
 
  ArgKeyword              ::= "ARGUMENT" | "PARAMETER"
 
  Result                  ::= "RESULT" ResultType | empty
 
  Errors                  ::= "ERRORS" "{"ErrorNames"}" | empty
 
  LinkedOperations        ::= "LINKED" "{"LinkedOperationNames"}" | empty
 
  ResultType              ::= NamedType | empty
 
  ErrorNames              ::= ErrorList | empty
 
  ErrorList               ::= Error | ErrorList "," Error
 
  Error                   ::= value(ERROR)        -- shall reference an error value
 
                              | type              -- shall reference an error type
 
                                                  -- if no error value is specified
 
  LinkedOperationNames    ::= OperationList | empty
 
  OperationList           ::= Operation | OperationList "," Operation
 
  Operation               ::= value(OPERATION)    -- shall reference an operation value
 
                              | type              -- shall reference an operation type
 
                                                  -- if no operation value is specified
 
  NamedType               ::= identifier type | type
 

 
END
 

This MACRO does not need to be defined in the ASN.1 specification to be parsed. In fact, any attempt to redefine this MACRO will be ignored. Its definition is hard-coded into the compiler.

What the compiler does with this definition is uses it to parse types and values out of OPERATION definitions. An example of an OPERATION definition is as follows:

login OPERATION 
 
ARGUMENT SEQUENCE { username IA5String, password IA5String }
 
RESULT   SEQUENCE { ticket OCTET STRING, welcomeMessage IA5String }
 
ERRORS { authenticationFailure, insufficientResources }
 
::= 1
 

In this case, there are two embedded types (an ARGUMENT type and a RESULT type) and an integer value (1) that identifies the OPERATION. There are also error definitions.

The ASN1C90 compiler generates two types of items for the OPERATION:

1. It extracts the type definitions from within the OPERATION definitions and generates equivalent C/C++ structures and encoders/decoders, and
   
2. It generates value constants for the value associated with the OPERATION (i.e., the value to the right of the `::=' in the definition).
   

The compiler does not generate any structures or code related to the OPERATION itself (for example, code to encode the body and header in a single step). The reason is because of the multi-layered nature of the protocol. It is assumed that the user of such a protocol would be most interested in doing the processing in multiple stages, hence no single function or structure is generated.

Therefore, to encode the login example the user would do the following:

1. At the application layer, the Login_ARGUMENT structure would be populated with the username and password to be encoded.
   
2. The encode function for Login_ARGUMENT would be called and the resulting message pointer and length would be passed down to the next layer (the ROSE layer).
   
3. At the ROSE layer, the Invoke structure would be populated with the OPERATION value, invoke identifier, and other header parameters. The parameter.numocts value would be populated with the length of the message passed in from step 2. The parameter.data field would be populated with the message pointer passed in from step 2.
   
4. The encode function for Invoke would be called resulting in a fully encoded ROSE Invoke message ready for transfer across the communications link.

The following is a picture showing this process:

On the decode side, the process would be reversed with the message flowing up the stack:

1. At the ROSE layer, the header would be decoded producing information on the OPERATION type (based on the MACRO definition) and message type (Invoke, Result, etc..). The invoke identifier would also be available for use in session management. In our example, we would know at this point that we got a login invoke request.
   
2. Based on the information from step 1, the ROSE layer would know that the Open Type field contains a pointer and length to an encoded Login_ARGUMENT component. It would then route this information to the appropriate processor within the Application Layer for handling this type of message.
   
3. The Application Layer would call the specific decoder associated with the Login_ARGUMENT. It would then have available to it the username/password the user is logging in with. It could then do whatever application-specific processing is required with this information (database lookup, etc.).
   
4. Finally, the Application Layer would begin the encoding process again in order to send back a Result or Error message to the Login Request.
   

A picture showing this is as follows:

The login OPERATION also contains references to ERROR definitions. These are defined using a separate MACRO that is built into the compiler. The definition of this MACRO is as follows:

ERROR MACRO ::=
 
BEGIN
 
  TYPE NOTATION     ::= Parameter
 

 
  VALUE NOTATION    ::= value (VALUE INTEGER)
 

 
  Parameter         ::= "PARAMETER" NamedType | empty
 

 
  NamedType         ::= identifier type | type
 

 
END 
 

In this definition, an error is assigned an identifying number as well as on optional parameter type to hold parameters associated with the error. An example of a reference to this MACRO for the authenticationFailure error in the login operation defined earlier would be as follows:

applicationError ERROR
 
PARAMETER SEQUENCE {
 
  errorText IA5String
 
}	}
 
::= 1
 

The ASN1C90 compiler will generate a type definition for the error parameter and a value constant for the error value. The format of the name of the type generated will be "<name>_PARAMETER" where <name> is the ERROR name (applicationError in this case) with the first letter set to uppercase. The name of the value will simply be the ERROR name.