WSDescription

Describes the REST function, parameters, and return values.

Syntax

WSDescription=" description "
Where:
  1. description provides a description of the parameter, function, or return value it is applied to.

WSDescription is an optional attribute.

Usage

You use this attribute to provide useful description for parameters in the function. You can set WSDescription on:
  • Any input and output parameter of a REST operation.
  • The attribute clause of the function.

Information you specify with the WSDescription attribute, is generated for the function in the OpenAPI specification file. You can control generation of descriptions in the stub file with the --comment option of the fglrestful tool.

Example using WSDescription

In this sample REST function a set of users is returned based on values provided in input parameters. WSDescription attributes provide descriptions of the parameters and the function. The function has three input parameters:
  • The stat parameter is set with the WSQuery and the WSName attributes. In a call to the function, the query string of the URI must be set by the name specified by WSName, such as http://myhost:6394/gas/ws/r/myGroup/myXcf/Accounts/users?status=1
  • The ccode parameter is set with the WSCookie, WSName, and the WSOptional attributes. If the client application calling the function provides a value for the cookie in the request, the name specified by WSName must be set in the query string of the URI, such as http://myhost:6394/gas/ws/r/myGroup/myXcf/Accounts/users?status=1&country=FRA
  • The cat parameter is set with the WSHeader, WSName, and the WSOptional attributes. The client application calling the function has the option of providing a value for a header named "category" in the request.
In the SQL query to the database, the COALESCE function is used to produce a query that supports the parameters that are optional and may have no values.

WSThrows is set to handle errors. In the TRY/CATCH block, the sqlca record is checked after the execution of the SQL query. The SQLERRMESSAGE is set to the message field of the userError variable, and a call to SetRestError() returns the message defined in WSThrows for the error. 

IMPORT com

TYPE profileType RECORD
     id INTEGER,
     name VARCHAR(100),
     email VARCHAR(255),
     category VARCHAR(10),
     status INTEGER,
     ccode VARCHAR(3)
     # ...
   END RECORD

PUBLIC DEFINE userError RECORD ATTRIBUTES(WSError = "User error")
  message STRING
END RECORD

PUBLIC FUNCTION getFilteredUsers(
    stat STRING ATTRIBUTES(WSQuery, WSName = "status",WSDescription = "Status is true(1) or false(0)" ),
    ccode STRING ATTRIBUTES(WSCookie, WSOptional, WSName = "country",WSDescription = "Country code"),
    cat STRING ATTRIBUTES(WSHeader, WSOptional, WSName = "category",WSDescription = "Product category")
    )
  ATTRIBUTES (WSGet,
              WSPath = "/filteredUsers",
              WSDescription = "Gets users based on query, cookie, and header values.",
              WSThrows = "400:Invalid,406:@userError" )
   RETURNS ( DYNAMIC ARRAY ATTRIBUTES(WSName = "Users_status",
             WSMedia = "application/json") OF profileType)
      
     DEFINE arr DYNAMIC ARRAY OF profileType
     DEFINE i INTEGER = 1
     TRY
       # The SQL COALESCE function produces a query that supports null parameters
       DECLARE c2 CURSOR FOR SELECT * FROM users
                               WHERE users.status = stat
                               AND users.country = COALESCE(ccode,users.country)
                               AND users.category = COALESCE(cat,users.category)
                               ORDER BY users.name ASC
       FOREACH c2 INTO arr[i].*
         LET i = i+1
       END FOREACH
       CALL arr.deleteElement(arr.getLength())
       # Remove the empty element implied by reference in FOREACH loop
     CATCH
       LET userError.message = SFMT("Error in SQL execution: %1 [%2]", 
                                     sqlca.sqlcode, SQLERRMESSAGE )
       CALL com.WebServiceEngine.SetRestError(406,userError)
     END TRY
     RETURN arr
END FUNCTION