/zosmf/variables/rest/1.0/systems/{system-id} is confusing - and provides no debg info

[colinpaicemq]

Describe the bug
A clear and concise description of what the bug is.

The swagger page says

Retrieve system variables/symbols for the {sysplex.sysname} specified in the request
....
system-id: Identifies the system in format sysplex-name.system-name. For system symbols, we only support local sysplex-name here.

because it returns system variables. Is the format sysplex-name.system-name. redundant?

When it says local sysplex name do you mean the local sysplex name?
For example
the operator command D SYMBOLS gives

D SYMBOLS                                                           
IEA007I STATIC SYSTEM SYMBOL VALUES 828                             
 &SYSALVL.          = "2"                                           
 &SYSCLONE.         = "1A"                                          
 &SYSNAME.          = "S0W1"                                        
 &SYSOSLVL.         = "Z1030100"                                    
 &SYSPLEX.          = "ADCDPL"                                      
 &SYSR1.            = "B3RES1"                                      

so is the swagger is saying specify ADCDPL? (Which is the wrong value to use)

I think it should be saying local system name = S0w1, because 2 systems in the sysplex could have different symbols.

The system name is 4 chars long, so giving a default of "local" feels wrong.

---

When I tried running this I got

{
"messages": [
{
"messageType": "ERROR",
"messageNumber": "ZWEAO503E",
"messageContent": "The server is not ready to handle the request: /ibmzosmf/api/v1/zosmf/variables/rest/1.0/systems/S0W1",
"messageAction": "Repeat the request later. Please contact support for further assistance.",
"messageReason": "The service is not ready to handle the request, it is being initialized or waiting for another service to start.",
"messageKey": "org.zowe.apiml.common.serviceUnavailable"
}
]
}

I looked in all the logs and could not find any error message or message text ( z/OSMF, ZOWe or z/oS),

Please enhance the message documentation with where to look eg /global/zosmf.

It maybe that the code is not generating an error message in the logs - and it should generate a message. This is a message that should go onto the z/OS syslog - so automation can pick it up and process it.

Steps to Reproduce

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Logs
If applicable, add server logs collected at the time of your problem.

Details

• Version and build number: [e.g. 0.4.4-SNAPSHOT build # 155]
• Test environment: [either defined Zowe test environment: Marist (1, 2, 3), River, or your own environment: z/OS version and z/OSMF version]

API Catalog Web UI (in case of API Catalog issue):

• OS: [e.g. macOS, Windows]
• Browser [e.g. Chrome, Safari]
• Version [e.g. 71.0.3578.98]

REST API client (in case of REST API issue):

• Technology: [e.g. Spring Boot, Node.js]
• OS: [e.g. Windows 10]

Additional context
Add any other context about the problem here.

Willingness to help
If you are willing to help with debugging and reproducing the problem or
with fixing the problem, please state your willingness to assist in the created issue.

https://github.com/zowe/api-layer/wiki/Issue-management

[balhar-jakub]

@colinpaicemq This error is linked to the z/OSMF service and as such the information and fixes needs to be provided in the z/OSMF information. From our side we just return the fact that the service returned 503 error to API Mediation Layer.

I am pinging @Joe-Winchester as he may know how to share this feedback with the IBM people related to the z/OSMF

[colinpaicemq]

Thank you... I thought this was calling another service before z/OSMF.

I've a couple of problems with z/OSMF - I'll add it to the list.

[Joe-Winchester]

Hi @colinpaicemq , let me know if you want help letting the z/OSMF team know. I can get a call with some of the team organized if you'd like to share some of what you've found.

[colinpaicemq]

Hi Joe, It would be good to have a contact in z/OSMF. For example Im trying to use zowe console, and getting back the following undocumented code { "reason": "POST TSO/E Service returns null.", "return-code": 3, "reason-code": 17 } With another area I also get return code 503 which I think is from z/OSMF. Knowing which traces to turn on would be a good start. I expect these problems are due to certificates, or not having the correct authorisation. Colin

…

On Wed, Jun 18, 2025 at 12:06 PM Joe Winchester ***@***.***> wrote: *Joe-Winchester* left a comment (zowe/community#2361) <#2361> Hi @colinpaicemq <https://github.com/colinpaicemq> , let me know if you want help letting the z/OSMF team know. I can get a call with some of the team organized if you'd like to share some of what you've found. — Reply to this email directly, view it on GitHub <#2361>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AJQXLWJZCTHUIH24DJGFVTL3EFB2RAVCNFSM6AAAAAB7J3AIU2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSOBTG42DMNRUHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[shreeji818]

I would like to answer first the questions related to "Retrieve system variables/symbols" REST API.

"system-id" field expects value in the form of sysplex-name.system-name that is identified in z/OSMF "Systems" task. System tasks allows you to define systems associated with z/OSMF. You can have systems defined in "Systems" task that are part of the same sysplex where z/OSMF is running or systems in different sysplex. For that reason, "system-id" is combination of "syplex-name.system-name" to uniquely identify system. Systems task also supports defining "system variables" for each of the systems that are defined in systems task. System variables can be used in z/OSMF workflows.

There is a special meaning of "system-id" value "local" which means the local z/OSMF system (system where z/OSMF is running). If there are system variables associated with the system, REST API returns those variables.

If there are more systems defined in z/OSMF "Systems" task than just "local" system and you want to retrieve system variable associated with those systems, you can specify system-id value in form of sysplex-name.system-name as represented in z/OSMF "Systems" task.

/zosmf/variables/rest/1.0/systems/{system-id} REST API also supports retrieving symbols when you invoke REST API with the query parm, i.e. /zosmf/variables/rest/1.0/systems/{system-id}?source=symbol

For system symbol also there is a special meaning of "system-id" value of "local" which means retrieving symbols from the local z/OSMF system.

For example, in z/OSMF Systems task, you have defined PLEX1 with SYS1 and SYS2 and z/OSMF is running on SYS1 and PLEX2 with SYS3 and SYS4. If you want to retrieve system symbol from SYS1, system-id value would be "PLEX1.SYS1" or you can also specify system-id value "local". To retrieve system symbols from SYS2, you need to explicitly specify "PLEX1.SYS2".

REST API only supports retrieving symbols from the systems that are in same sysplex where z/OSMF is running. For above example, if you specify system-id value "PLEX2.SYS3" which is a different sysplex than where z/OSMF is running, REST API will fail. For that reason swagger document has following statement where local sysplex-name means specify sysplex-name that is associated with z/OSMF.
"For system symbols, we only support local sysplex-name here".

Based on Swagger documentation and z/OSMF code, I don't see z/OSMF has 503 response code. So, I don't think "ZWEAO503E" would mean z/OSMF is returning 503. It might be coming from API mediation layer. @balhar-jakub will you please confirm?

[shreeji818]

@colinpaicemq will you please provide further information about TSO REST API failure? You may open a case with IBM if the REST API is abnormally failing. What response code you are getting from REST API call?

{
"reason": "POST TSO/E Service returns null.",
"return-code": 3,
"reason-code": 17
}

You can turn on additional tracing in z/OSMF by using z/OSMF Diagnostics Assistant task. Here you can select the z/OSMF function (aka Service) for which you want to collect additional trace,

There are different trace level supported. If you suspect code issue, please capture "ALL" trace and send it to IBM for analysis. Please click "Set" to enable trace.