Class Reference
IRIS for UNIX 2019.2
InterSystems: The power behind what matters   
Documentation  Search
  [ENSLIB] >  [%Api] >  [Atelier] >  [v2]
Private  Storage   

class %Api.Atelier.v2 extends %Api.Atelier.v1

%Api.Atelier.v2 provides version 2 APIs for Atelier

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
12


Summary

Methods
%ClassIsLatestVersion %ClassName %DispatchClassMethod %DispatchGetModified
%DispatchGetProperty %DispatchMethod %DispatchSetModified %DispatchSetMultidimProperty
%DispatchSetProperty %Extends %GetParameter %IsA
%New %OriginalNamespace %PackageName %SetModified
AcceptsContentType AccessCheck Compile ConvertParameter
CreateSourceControlClass CvtClientDocToXml CvtXmlToClientDoc Decrypt
DeleteDoc DeleteDocs DispatchMap DispatchRequest
DrawCSS3STYLE DrawHEAD DrawSTHEAD DrawSTTitle
DrawSTYLE DrawTitle DrawTitleSection Encrypt
Error EscapeHTML EscapeURL GetAdpInputOutputClass
GetCSPApps GetCSPDebugId GetDoc GetDocNames
GetDocs GetEnsClassType GetJobs GetMacroDefinition
GetMacroExpansion GetMacroList GetMacroLocation GetMacroSignature
GetMetaData GetModifiedDocNames GetNamespace GetNamespaces
HeadDoc Http403 Http404 Http405
Http500 HyperEventCall HyperEventHead Include
Index InsertHiddenField InsertHiddenFields IsPrivate
Link Login OnErrorSetup OnHTTPHeader
OnHandleCorsRequest OnHandleOptionsRequest OnLoginPage OnPage
OnPageError OnPostHTTP OnPostHyperEvent OnPreDispatch
OnPreHTTP OnPreHyperEvent OnSecurityTokenPage Page
PutDoc Query QuoteJS RenderResponseBody
ReportHttpStatusCode ResolveTarget RewriteURL RunDebugger
Search ServeDoc ServeXml SetClientServerHash
SetResponseHeaderIfEmpty ShowError StartTimer StatusToJSON
StatusToProxyObject StopTimer SupportedVerbs ThrowError
UnescapeHTML UnescapeURL

Subclasses
%Api.Atelier.v3

Methods

• classmethod GetCSPDebugId() as %Status
This method returns an id for use with CSP debugging

GET http://localhost:57772/api/atelier/v2/%25SYS/cspdebugid

HTTP Codes returned:-

HTTP 200 if OK
HTTP 500 if an error occurs (details will be in status error array)

Returned content is an integer debug identifier
{ "status": { "errors": [], "summary": "" }, "console": [], "result": { "content": { id: NNNNNN } } }
• classmethod GetDoc(pNamespace As %String, pDocName As %String) as %Status
This method returns the text for the named document and namespace.

HTTP Codes returned:-

HTTP 200 if OK
HTTP 304 if the document has not been modified (see https://en.wikipedia.org/wiki/HTTP_ETag)
HTTP 400 if the named resource is not a valid document name
HTTP 404 if the document does not exist
HTTP 500 if an unxpected error occurs (details will be in status error array)

Return content will contain a document object.
Errors pertaining to the document will be in the status property of the document object. If source control hooks are enabled for the namespace any console output generated by the hook will be captured and returned as an array of lines in the 'console' array.

The result contains the name of the requested document, the database where it is stored, its timestamp and category (CLS - class, RTN - routine, CSP - csp, OTH - other), as well as the document contents which are returned in an array.

For text documents this will be an array of strings and the 'enc' json field will be set to false.
For binary documents this will be an array of base64 encoded chunks and the 'enc' field will be set to true.

The URL parameter ?binary=1 can be passed to force the document to be encoded as binary.

The URL parameter ?storageOnly=1 can be passed to return only the storage portion of a class.

The URL parameter ?format= can be passed to specify the source format. The choices are "udl" (the default) or "xml".

If a 'soft' error occurs such as a 'document does not exist', additional information can be found in the 'status' field of the result. Examples of other soft errors are 'file is locked' etc.

Here is an example of the result of asking for %Activate.Enum.cls
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "%Activate.Enum.cls",
    "db": "IRISLIB",
    "ts": "2016-01-04 14:00:04.000",
    "cat": "CLS",
    "status": "",
    "enc": false,
    "content": [
      "/// This class is the superclass for all enumerated types generated from",
      "/// a type library",
      "Class %Activate.Enum Extends %Integer [ Not ProcedureBlock, System = 3 ]",
      "{",
      "",
      "}",
      ""
    ]
  }
}

and here is the result with ?binary=1
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "%Activate.Enum.cls",
    "db": "IRISLIB",
    "ts": "2016-01-04 14:00:04.000",
    "cat": "CLS",
    "status": "",
    "enc": true,
    "content": [
      "Ly8vIFRoaXMgY2xhc3MgaXMgdGhlIHN1cGVyY2xhc3MgZm9yIGFsbCBlbnVtZXJhdGVkIHR5cGVzIGdlbmVyYXRlZCBmcm9tCi8vLyBhIHR5cGUgbGlicmFyeQpDbGFzcyAlQWN0aXZhdGUuRW51bSBFeHRlbmRzICVJbnRlZ2VyIFsgTm90IFByb2NlZHVyZUJsb2NrLCBTeXN0ZW0gPSAzIF0KewoKfQo="
    ]
  }
}
• classmethod GetMacroDefinition(pNamespace As %String) as %Status
Input request:
{
  "docname": "MyClass.cls",
  "macroname": "mymac",
  "superclasses": ["class1",...],
  "includes": ["include1",...],
  "includegenerators": ["generator1",...],
  "imports": ["package1",...],
  "mode": "generator" or ""
}
Returned content:
{
  "status": { "errors": [],  "summary": "" },
  "console": [],
  "result": {
    "content": {
      "definition": ["line1","line2",...]
    }
  }
}
• classmethod GetMacroExpansion(pNamespace As %String) as %Status
Input request:
{
  "docname": "MyClass.cls",
  "macroname": "mymac",
  "arguments": "(arg1,arg2,...)",
  "superclasses": ["class1",...],
  "includes": ["include1",...],
  "includegenerators": ["generator1",...],
  "imports": ["package1",...],
  "mode": "generator" or ""
}
Returned content:
{
  "status": { "errors": [],  "summary": "" },
  "console": [],
  "result": {
    "content": {
      "expansion": ["line1","line2",...]
    }
  }
}
• classmethod GetMacroList(pNamespace As %String) as %Status
Input request:
{
  "docname": "MyClass.cls",
  "hash": "XXXX",
  "cursor": "XXX",
  "superclasses": ["class1",...],
  "includes": ["include1",...],
  "includegenerators": ["generator1",...],
  "imports": ["package1",...],
  "mode": "generator" or ""
}
"hash" is a null string or the value returned from a previous call for this document. If the server contents have not changed, the result will be this same hash value and nothing else.
"cursor" is a null string or the value returned from the previous call.

Returned content:
{
  "status": { "errors": [],  "summary": "" },
  "console": [],
  "result": {
    "content": {
      "hash": "XXXX",
      "cursor": "XXXX",
      "macros": ["macro1",...]
    }
  }
}
"hash" is a value indicating the current contents of the server. If this value is passed in the next request for this document and the server contents have not changed, nothing needs to be returned.
"cursor" will be the null string if the macro list is complete. If it is not null, another call should be made, passing this cursor value, to get the next part of the macro list.
• classmethod GetMacroLocation(pNamespace As %String) as %Status
Input request:
{
  "docname": "MyClass.cls",
  "macroname": "mymac",
  "superclasses": ["class1",...],
  "includes": ["include1",...],
  "includegenerators": ["generator1",...],
  "imports": ["package1",...],
  "mode": "generator" or ""
}
Returned content:
{
  "status": { "errors": [],  "summary": "" },
  "console": [],
  "result": {
    "content": {
      "document": "name.inc",
      "line": lineno
    }
  }
}
• classmethod GetMacroSignature(pNamespace As %String) as %Status
Input request:
{
  "docname": "MyClass.cls",
  "macroname": "mymac",
  "superclasses": ["class1",...],
  "includes": ["include1",...],
  "includegenerators": ["generator1",...],
  "imports": ["package1",...],
  "mode": "generator" or ""
}
Returned content:
{
  "status": { "errors": [],  "summary": "" },
  "console": [],
  "result": {
    "content": {
      "signature": "(arg1,arg2)"
    }
  }
}
• classmethod PutDoc(pNamespace As %String, pDocName As %String) as %Status
This method saves the supplied document

HTTP Codes returned:-

HTTP 201 if created
HTTP 400 if the resource name is an invalid document name
HTTP 404 if the resource is not found
HTTP 409 if a conflict between server and client versions is detected
HTTP 415 if not passed text/plain as content type
HTTP 425 if the document is locked and cannot be written to
HTTP 500 if an error occurs (details will be in status error array)

Return content will be a document object.
Errors pertaining to the document will be in the status property of the document object.

The URL parameter ?ignoreConflict=1 can be passed to bypass ETAG checking (see reference
above in 'GetDoc') and force the document to be written on the server.

Note that if the text on the server is changed during the save process (for example
by a source control hook) the new text will be returned in the content array
of the returned document.

Here is an example of a PUT for the document xyz.mac
{
 "enc": false,
 "content": [
   "ROUTINE xyz",
   "xyz ;",
   "   w \"hello\""
   ]
}


and the corresponding response :-
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [
  ],
  "result": {
    "name": "xyz.mac",
    "db": "IRISSYS",
    "ts": "2016-01-12 17:18:29.332",
    "cat": "RTN",
    "status": "",
    "enc": false,
    "content": []
  }
}
• classmethod RunDebugger() as %Status
• classmethod Search(pNamespace As %String) as %Status
This method searches a set of documents using a Regular Expression or a text string.

HTTP Codes returned:-

HTTP 200 if request is OK
HTTP 400 if there are missing arguments

Input request:
GET localhost:57772/api/atelier/v2/:namespace/action/search?query=expr&documents=list&sys=1&gen=1&regex=1&max=200
Required arguments are:
query = the search expression, a regular expression or a plain text string
documents = a comma-separated list of documents or masks with the * wild card

Optional arguments are:
regex = 0 or 1 (default 1) whether the query string is a regular expression or not
sys = 0 or 1 (default 0) include sytem documents in the search
gen = 0 or 1 (default 0) include generated documents in the search
max = nnn (default 200) maxinum number of results to return

The result is returned as the console output of the search and as a JSON array.

Example input to search for the word Email in all classes and MAC routines:
GET localhost:57772/api/atelier/v2/SAMPLES/action/search?query=.*\bEmail\b.*&documents=*.cls,*.mac
Returned content (some is omitted here):
{
  "status": { "errors": [],  "summary": "" },
  "console": [
    "",
    "Searching for '.*\\bEmail\\b.*' in '*.cls,*.mac'",
    "Cinema.Utils.cls(SendEmail+28): Quit \"Email confirmation has been sent to \" _ Addr",
    "Wasabi.Data.Employee.cls(Email)[Type]: Wasabi.Common.DT.Email",
    "Wasabi.Data.Employee.cls(CopyFrom+26): set ..Email = employee.Email",
    "ZAUTHENTICATE.mac(175): Properties(\"EmailAddress\") - Email address",
    "Found 11 occurrence/s in 7 file/s."
  ],
  "result": [
    {
      "doc": "Cinema.Utils.cls",
      "matches": [
        {
         "member": "SendEmail",
         "line": 28,
         "text": "Quit \"Email confirmation has been sent to \" _ Addr"
        }
      ]
    },
    {
      "doc": "Wasabi.Data.Employee.cls",
      "matches": [
        {
         "member": "Email",
         "attr": "Type",
         "text": "Wasabi.Common.DT.Email"
        },
        {
         "member": "CopyFrom",
         "line": 26,
         "text": "set ..Email = employee.Email"
        }
      ]
    },
    {
      "doc": "ZAUTHENTICATE.mac",
      "matches": [
        {
         "line": "175",
         "text": "Properties(\"EmailAddress\") - Email address"
        }
      ]
    }
  ]
}


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.