====== RTI_Res2Str Function     ======


 
==== Description ====
 
This stored procedure returns a "resource string" for a specified identifier, optionally swapping out placeholder strings with auxiliary arguments.
 
==== Syntax ====
 
resText = RTI_Res2Str( resID, resCode, resArgs, bRemoveCode )
 
==== Parameters ====
 
The function has the following parameters:

^Parameter^Description^
|resID [required]|Contains the name of the record containing the resource string.  This should have the format:\\ \\  \\ \\ <resname> “_RESOURCES”\\ \\  \\ \\ e.g. “SFX_RESOURCES”\\ \\  \\ \\ In this case the resource record is assumed to be in the SYSENV table.\\ \\  \\ \\ Or\\ \\  \\ \\ <table> “:” <resname> “_RESOURCES”\\ \\  \\ \\ (e.g. “SFX_ENV:SFX_RESOURCES”)\\ \\  \\ \\ In this case the table name is specified in the as part of the resID argument.\\ \\  \\ \\ If resID is null the function defaults to using the SYSTEM_RESOURCES record in the SYSENV table.\\ \\  \\ \\ If resID is not suffixed with the string “_RESOURCES” it is automatically added at runtime.\\ \\  \\ \\ Language specific resource records will be used in preference where possible if the system has a language code set by the Set_Language function. In this case the resource record must be stored with the appropriate LNG suffix appended to it’s ID (separated by a hyphen).\\ \\  \\ \\ e.g.\\ \\  \\ \\ “SFX_RESOURCES-ITA” (Italian version of SFX_RESOURCES)\\ \\ “SFX_RESOURCES-DEU” (German version of SFX_RESOURCES)|
|resCode [required]|Code that identifies the required string in the resource record.\\ \\  \\ \\ e.g.\\ \\  \\ \\ “UTL002”, “RTPS01.02” and so on.|
|resArgs [Optional]|Contains an @fm-delimited list of arguments to replace numeric placeholder tokens in the resource string (This works in a similar fashion to the Msg() function).\\ \\  \\ \\ i.e.\\ \\  \\ \\ The token “%1%” will be replaced by the first field in the resArgs parameter.\\ \\ The token “%2%” will is replaced by the second field in the resArgs parameter.\\ \\  \\ \\ And so on.|
|bRemoveCode [Optional]|Normally resource strings are returned prefixed with their code.  If this parameter is TRUE$ then the code is removed before the string is returned.\\ \\  \\ \\ e.g.\\ \\  \\ \\ “RTPS02.01: Invalid method "%1%" passed to the %2% procedure “\\ \\  \\ \\ Is returned as:\\ \\  \\ \\ “Invalid method "%1%" passed to the %2% procedure “\\ \\  \\ \\ The default value is FALSE$.||

 
==== Returns ====
 
Returns the specified resource string.  Errors are returned via Set_Status().
 
==== Remarks ====
 
 
 
==== See Also ====
 
 
 
==== Example ====
 

The following resource record called RTPS_RESOURCES is stored in the SYSENV table:

  
<code>
  RTPS02.01: Invalid method "%1%" passed to the %2% procedure

  RTPS02.02: Error opening the SYSLISTS table in the %1% "%2%" method [%3%]

  RTPS02.03: No method passed to the %1% procedure
</code>
  

To extract a resource string:

<code>
   declare function RTI_Res2Str, retStack

   $insert logical

   equ RESID$ to "RTPS_RESOURCES"

   if len( method ) else

      * // RTPS02.03: No method passed to the %1% procedure

      errorText = rti_Res2Str( RESID$,       

                               "RTPS02.03",  

                               retStack()<1> )

   end

</code>